/ Hex Artifact Content
Login

Artifact 37a520846e4b4479738855d146b10f7abcb1bb66:


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 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
8580: 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  l guarantee that
8590: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
85a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
85b0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
85c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
85d0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
85e0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
85f0: 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74  thname().  SQLit
8600: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
8610: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
8620: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
8630: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
8640: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
8650: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
8660: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
8670: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
8680: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
8690: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
86a0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
86b0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
86c0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
86d0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
86e0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
86f0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
8700: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
8710: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f   parameter is xO
8720: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
8730: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
8740: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
8750: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
8760: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
8770: 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74  ile.  Whenever t
8780: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
8790: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
87a0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
87b0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
87c0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
87d0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
87e0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
87f0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8800: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
8810: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
8820: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
8830: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
8840: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
8850: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
8860: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
8870: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
8880: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
8890: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
88a0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
88b0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
88c0: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
88d0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
88e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
88f0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
8900: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
8910: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
8920: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
8930: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
8940: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
8950: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
8960: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
8970: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
8980: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
8990: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
89a0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
89b0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
89c0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
89d0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
89e0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
89f0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
8a00: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8a10: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
8a20: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8a30: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
8a40: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
8a50: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
8a60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8a70: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
8a80: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
8a90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
8aa0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
8ab0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8ac0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
8ad0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8ae0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
8af0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8b00: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
8b10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
8b20: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
8b30: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
8b40: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
8b50: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
8b60: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
8b70: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
8b80: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
8b90: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
8ba0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
8bb0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
8bc0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
8bd0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
8be0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
8bf0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
8c00: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
8c10: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
8c20: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
8c30: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
8c40: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
8c50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
8c60: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
8c70: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
8c80: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
8c90: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
8ca0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
8cb0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
8cc0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
8cd0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
8ce0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
8cf0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
8d00: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
8d10: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
8d20: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
8d30: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
8d40: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
8d50: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
8d60: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
8d70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
8d80: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
8d90: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
8da0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
8db0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
8dc0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8dd0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
8de0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
8df0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
8e00: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
8e10: 73 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  sed.  The [SQLIT
8e20: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
8e30: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
8e40: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64   set for TEMP  d
8e50: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61  atabases, journa
8e60: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f  ls and for subjo
8e70: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  urnals..**.** Th
8e80: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
8e90: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
8ea0: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
8eb0: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
8ec0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
8ed0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
8ee0: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
8ef0: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
8f00: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
8f10: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
8f20: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
8f30: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
8f40: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
8f50: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
8f60: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
8f70: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
8f80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8f90: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
8fa0: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
8fb0: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
8fc0: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
8fd0: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
8fe0: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
8ff0: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
9000: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
9010: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
9020: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
9030: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
9040: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
9050: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65  ess..**.** At le
9060: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
9070: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
9080: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
9090: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
90a0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
90b0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
90c0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
90d0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
90e0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
90f0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
9100: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
9110: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
9120: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
9130: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
9140: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
9150: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
9160: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
9170: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
9180: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
9190: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
91a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
91b0: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
91c0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
91d0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
91e0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
91f0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
9200: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
9210: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
9220: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
9230: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
9240: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
9250: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
9260: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
9270: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
9280: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  call..**.** The 
9290: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
92a0: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
92b0: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
92c0: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
92d0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
92e0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
92f0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
9300: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
9310: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
9320: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
9330: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
9340: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
9350: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
9360: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
9370: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
9380: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
9390: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
93a0: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
93b0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  ** SQLite will a
93c0: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
93d0: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
93e0: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
93f0: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
9400: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
9410: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
9420: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
9430: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
9440: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
9450: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
9460: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
9470: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
9480: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
9490: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
94a0: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
94b0: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
94c0: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
94d0: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
94e0: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
94f0: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
9500: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
9510: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
9520: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
9530: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
9540: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
9550: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
9560: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
9570: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
9580: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
9590: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
95a0: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
95b0: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
95c0: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
95d0: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
95e0: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
95f0: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
9600: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
9610: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
9620: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
9630: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
9640: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
9650: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
9660: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
9670: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
9680: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
9690: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
96a0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
96b0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
96c0: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
96d0: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
96e0: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
96f0: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
9700: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
9710: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
9720: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
9730: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
9740: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
9750: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
9760: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
9770: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
9780: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
9790: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
97a0: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
97b0: 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 78 43  value..** The xC
97c0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
97d0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
97e0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
97f0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
9800: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
9810: 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  led by 86400000 
9820: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
9830: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
9840: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
9850: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
9860: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
9870: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
9880: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
9890: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
98a0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
98b0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
98c0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
98d0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
98e0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
98f0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
9900: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
9910: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
9920: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
9930: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
9940: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
9950: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2f   unavailable..*/
9960: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
9970: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
9980: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20  te3_vfs;.struct 
9990: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
99a0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
99b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
99c0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
99d0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
99e0: 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  2) */.  int szOs
99f0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
9a00: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
9a10: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
9a20: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
9a30: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
9a40: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
9a50: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
9a60: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
9a70: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
9a80: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
9a90: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
9aa0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
9ab0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
9ac0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
9ad0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
9ae0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
9af0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
9b00: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
9b10: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
9b20: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
9b30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9b40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9b50: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
9b60: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
9b70: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
9b80: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
9b90: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
9ba0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9bb0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
9bc0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
9bd0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
9be0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9bf0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
9c00: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
9c10: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
9c20: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
9c30: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
9c40: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
9c50: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
9c60: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
9c70: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
9c80: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
9c90: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
9ca0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
9cb0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
9cc0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
9cd0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
9ce0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
9cf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
9d00: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9d10: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
9d20: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
9d30: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
9d40: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
9d50: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
9d60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
9d70: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
9d80: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
9d90: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
9da0: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
9db0: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
9dc0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
9dd0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
9de0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
9df0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
9e00: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
9e10: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
9e20: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
9e30: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
9e40: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
9e50: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
9e60: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
9e70: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
9e80: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
9e90: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
9ea0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
9eb0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
9ec0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
9ed0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
9ee0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
9ef0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
9f00: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
9f10: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
9f20: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
9f30: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
9f40: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
9f50: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
9f60: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
9f70: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
9f80: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
9f90: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
9fa0: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
9fb0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
9fc0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
9fd0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
9fe0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
9ff0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
a000: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
a010: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
a020: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
a030: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
a040: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
a050: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
a060: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
a070: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
a080: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
a090: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
a0a0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a0b0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
a0c0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
a0d0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
a0e0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
a0f0: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
a100: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
a110: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
a120: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a130: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a140: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
a150: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
a160: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
a170: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
a180: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
a190: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
a1a0: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
a1b0: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
a1c0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
a1d0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
a1e0: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
a1f0: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
a200: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
a210: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
a220: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
a230: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
a240: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
a250: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
a260: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
a270: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a280: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
a290: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a2a0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a2b0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
a2c0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
a2d0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
a2e0: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
a2f0: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
a300: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
a310: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
a320: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
a330: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
a340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a350: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
a360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
a370: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
a380: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
a390: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
a3a0: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
a3b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a3c0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
a3d0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
a3e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
a3f0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
a400: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
a410: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
a420: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
a430: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
a440: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
a450: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
a460: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
a470: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
a480: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
a490: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
a4a0: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
a4b0: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
a4c0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
a4d0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
a4e0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
a4f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
a500: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
a510: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
a520: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
a530: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
a540: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
a550: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
a560: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
a570: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
a580: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
a590: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
a5a0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
a5b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
a5c0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
a5d0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
a5e0: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
a5f0: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
a600: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
a610: 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   no the correspo
a620: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
a630: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
a640: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
a650: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
a660: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
a670: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
a680: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
a690: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
a6a0: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
a6b0: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
a6c0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
a6d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a6e0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
a6f0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
a700: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
a710: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
a720: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
a730: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
a740: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
a750: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
a760: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
a770: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
a780: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
a790: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
a7a0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
a7b0: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
a7c0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
a7d0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
a7e0: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
a7f0: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
a800: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
a810: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
a820: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
a830: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
a840: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
a850: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
a860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
a870: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
a880: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
a890: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
a8a0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
a8b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
a8c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a8d0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
a8e0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
a8f0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
a900: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
a910: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
a920: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
a930: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
a940: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
a950: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a960: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
a970: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
a980: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
a990: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
a9a0: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
a9b0: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
a9c0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
a9d0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
a9e0: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
a9f0: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
aa00: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
aa10: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
aa20: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
aa30: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
aa40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
aa50: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
aa60: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
aa70: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
aa80: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
aa90: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
aaa0: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
aab0: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
aac0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
aad0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
aae0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
aaf0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
ab00: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
ab10: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
ab20: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ab30: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
ab40: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
ab50: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
ab60: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
ab70: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
ab80: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
ab90: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
aba0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
abb0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
abc0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
abd0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
abe0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
abf0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
ac00: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ac10: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
ac20: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
ac30: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
ac40: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
ac50: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
ac60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
ac70: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
ac80: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
ac90: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
aca0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
acb0: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
acc0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
acd0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ace0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
acf0: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
ad00: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
ad10: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
ad20: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
ad30: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ad40: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
ad50: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
ad60: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
ad70: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
ad80: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
ad90: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
ada0: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
adb0: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
adc0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
add0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
ade0: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
adf0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
ae00: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
ae10: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
ae20: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
ae30: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
ae40: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
ae50: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
ae60: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
ae70: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
ae80: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
ae90: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
aea0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
aeb0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
aec0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
aed0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
aee0: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
aef0: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
af00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
af10: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
af20: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
af30: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
af40: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
af50: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
af60: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
af70: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
af80: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
af90: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
afa0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
afb0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
afc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
afd0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
afe0: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
aff0: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
b000: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
b010: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
b020: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
b030: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
b040: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
b050: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b060: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
b070: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
b080: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
b090: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
b0a0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
b0b0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
b0c0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
b0d0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
b0e0: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
b0f0: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
b100: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
b110: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
b120: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
b130: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
b140: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b150: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
b160: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
b170: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b180: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
b190: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
b1a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b1b0: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
b1c0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
b1d0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
b1e0: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
b1f0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b200: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
b210: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
b220: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
b230: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
b240: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
b250: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
b260: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
b270: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
b280: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b290: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
b2a0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
b2b0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
b2c0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
b2d0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
b2e0: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
b2f0: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
b300: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
b310: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
b320: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
b330: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b340: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
b350: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
b360: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
b370: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
b380: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
b390: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
b3a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
b3b0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
b3c0: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
b3d0: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
b3e0: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
b3f0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
b400: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
b410: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
b420: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
b430: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
b440: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
b450: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
b460: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
b470: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
b480: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
b490: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
b4a0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
b4b0: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
b4c0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
b4d0: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
b4e0: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
b4f0: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
b500: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
b510: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
b520: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
b530: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
b540: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b550: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
b560: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
b570: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
b580: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
b590: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
b5a0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
b5b0: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
b5c0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
b5d0: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
b5e0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b5f0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
b600: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
b610: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
b620: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
b630: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
b640: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
b650: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
b660: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
b670: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
b680: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
b690: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
b6a0: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
b6b0: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
b6c0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
b6d0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
b6e0: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
b6f0: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
b700: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
b710: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
b720: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
b730: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
b740: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
b750: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
b760: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
b770: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
b780: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
b790: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
b7a0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
b7b0: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
b7c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
b7d0: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
b7e0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
b7f0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
b800: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
b810: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
b820: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
b830: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
b840: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
b850: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
b860: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
b870: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
b880: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
b890: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
b8a0: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
b8b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b8c0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
b8d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
b8e0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
b8f0: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
b900: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
b910: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
b920: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
b930: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
b940: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
b950: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
b960: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
b970: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
b980: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
b990: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
b9a0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
b9b0: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
b9c0: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
b9d0: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
b9e0: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
b9f0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
ba00: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
ba10: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
ba20: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
ba30: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
ba40: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
ba50: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
ba60: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
ba70: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
ba80: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
ba90: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
baa0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
bab0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
bac0: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
bad0: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
bae0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
baf0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
bb00: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
bb10: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
bb20: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
bb30: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
bb40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
bb50: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
bb60: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
bb70: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
bb80: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
bb90: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
bba0: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
bbb0: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
bbc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bbd0: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
bbe0: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
bbf0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
bc00: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
bc10: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
bc20: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
bc30: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
bc40: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
bc50: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
bc60: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
bc70: 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
bc80: 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
bc90: 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
bca0: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
bcb0: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
bcc0: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
bcd0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
bce0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
bcf0: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
bd00: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
bd10: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
bd20: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
bd30: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
bd40: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ger.** [SQLITE_C
bd50: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
bd60: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
bd70: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
bd80: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
bd90: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
bda0: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
bdb0: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
bdc0: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
bdd0: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
bde0: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54  ng on the [SQLIT
bdf0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
be00: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
be10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
be20: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
be30: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
be40: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
be50: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
be60: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
be70: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
be80: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
be90: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
bea0: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
beb0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
bec0: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
bed0: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
bee0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
bef0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
bf00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
bf10: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
bf20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
bf30: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
bf40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
bf50: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
bf60: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
bf70: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
bf80: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
bf90: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
bfa0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
bfb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
bfc0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
bfd0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
bfe0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
bff0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
c000: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
c010: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
c020: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c030: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
c040: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
c050: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
c060: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c070: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
c080: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
c090: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
c0a0: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
c0b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c0c0: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
c0d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c0e0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
c0f0: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
c100: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c110: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
c120: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
c130: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c140: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
c150: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
c160: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
c170: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
c180: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
c190: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
c1a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c1b0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
c1c0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
c1d0: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
c1e0: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
c1f0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
c200: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
c210: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
c220: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
c230: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
c240: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
c250: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
c260: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
c270: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
c280: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
c290: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
c2a0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
c2b0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
c2c0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
c2d0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
c2e0: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
c2f0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
c300: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
c310: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
c320: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
c330: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
c340: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
c350: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c360: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
c370: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
c380: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
c390: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
c3a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
c3b0: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
c3c0: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
c3d0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
c3e0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
c3f0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
c400: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
c410: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
c420: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
c430: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
c440: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
c450: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
c460: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
c470: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
c480: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
c490: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
c4a0: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
c4b0: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
c4c0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c4d0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
c4e0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
c4f0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
c500: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
c510: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
c520: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
c530: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
c540: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
c550: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
c560: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
c570: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
c580: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
c590: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
c5a0: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
c5b0: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
c5c0: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
c5d0: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
c5e0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
c5f0: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
c600: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
c610: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
c620: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
c630: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
c640: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
c650: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
c660: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
c670: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
c680: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
c690: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
c6a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c6b0: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
c6c0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
c6d0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
c6e0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
c6f0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
c700: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
c710: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
c720: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
c730: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
c740: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
c750: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
c760: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
c770: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
c780: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
c790: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
c7a0: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
c7b0: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
c7c0: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
c7d0: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
c7e0: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
c7f0: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
c800: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
c810: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
c820: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
c830: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
c840: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
c850: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
c860: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
c870: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
c880: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
c890: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
c8a0: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
c8b0: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
c8c0: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
c8d0: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
c8e0: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
c8f0: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
c900: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
c910: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c920: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
c930: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
c940: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
c950: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
c960: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
c970: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
c980: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
c990: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
c9a0: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
c9b0: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
c9c0: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
c9d0: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
c9e0: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
c9f0: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
ca00: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
ca10: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
ca20: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
ca30: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
ca40: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
ca50: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
ca60: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
ca70: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
ca80: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
ca90: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
caa0: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
cab0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cac0: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
cad0: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
cae0: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
caf0: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
cb00: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
cb10: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
cb20: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
cb30: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
cb40: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
cb50: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
cb60: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
cb70: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
cb80: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
cb90: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
cba0: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
cbb0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
cbc0: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
cbd0: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
cbe0: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
cbf0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
cc00: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
cc10: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
cc20: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
cc30: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
cc40: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
cc50: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
cc60: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
cc70: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
cc80: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
cc90: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
cca0: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
ccb0: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
ccc0: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
ccd0: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
cce0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
ccf0: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
cd00: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
cd10: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
cd20: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
cd30: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
cd40: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
cd50: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
cd60: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
cd70: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
cd80: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
cd90: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
cda0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
cdb0: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
cdc0: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
cdd0: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
cde0: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
cdf0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
ce00: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
ce10: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
ce20: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
ce30: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
ce40: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
ce50: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
ce60: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
ce70: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
ce80: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
ce90: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
cea0: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
ceb0: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
cec0: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
ced0: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
cee0: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
cef0: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
cf00: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
cf10: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
cf20: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
cf30: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
cf40: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
cf50: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
cf60: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
cf70: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
cf80: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
cf90: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
cfa0: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
cfb0: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
cfc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
cfd0: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
cfe0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
cff0: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
d000: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
d010: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
d020: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
d030: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
d040: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
d050: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
d060: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
d070: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
d080: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
d090: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
d0a0: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
d0b0: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
d0c0: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
d0d0: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
d0e0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
d0f0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
d100: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
d110: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
d120: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
d130: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
d140: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
d150: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d160: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d170: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d180: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
d190: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d1a0: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
d1b0: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
d1c0: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
d1d0: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
d1e0: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
d1f0: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
d200: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
d210: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
d220: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
d230: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
d240: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
d250: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
d260: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
d270: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
d280: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
d290: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
d2a0: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
d2b0: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
d2c0: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
d2d0: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
d2e0: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
d2f0: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
d300: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
d310: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
d320: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d330: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d340: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
d350: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
d360: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
d370: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
d380: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
d390: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
d3a0: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
d3b0: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
d3c0: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
d3d0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d3e0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
d3f0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
d400: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
d410: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
d420: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
d430: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d440: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
d450: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
d460: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
d470: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
d480: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
d490: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
d4a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d4b0: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
d4c0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
d4d0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
d4e0: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
d4f0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
d500: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
d510: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
d520: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
d530: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
d540: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
d550: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
d560: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
d570: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
d580: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
d590: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d5a0: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
d5b0: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
d5c0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
d5d0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
d5e0: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
d5f0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d600: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
d610: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
d620: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d630: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
d640: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
d650: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
d660: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
d670: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
d680: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
d690: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
d6a0: 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
d6b0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
d6c0: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
d6d0: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
d6e0: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
d6f0: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
d700: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
d710: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
d720: 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
d730: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
d740: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
d750: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
d760: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
d770: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
d780: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
d790: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
d7a0: 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
d7b0: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
d7c0: 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
d7d0: 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
d7e0: 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
d7f0: 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
d800: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
d810: 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
d820: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
d830: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
d840: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
d850: 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
d860: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
d870: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d880: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
d890: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
d8a0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
d8b0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
d8c0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
d8d0: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
d8e0: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
d8f0: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
d900: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
d910: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
d920: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
d930: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
d940: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
d950: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
d960: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
d970: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
d980: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
d990: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
d9a0: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
d9b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
d9c0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
d9d0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
d9e0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
d9f0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
da00: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
da10: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
da20: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
da30: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
da40: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
da50: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
da60: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
da70: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
da80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
da90: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
daa0: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
dab0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
dac0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
dad0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
dae0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
daf0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
db00: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
db10: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
db20: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
db30: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
db40: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
db50: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
db60: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
db70: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
db80: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
db90: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
dba0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
dbb0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
dbc0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
dbd0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
dbe0: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
dbf0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
dc00: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
dc10: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
dc20: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
dc30: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
dc40: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
dc50: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
dc60: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
dc70: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
dc80: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
dc90: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
dca0: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
dcb0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
dcc0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
dcd0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
dce0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
dcf0: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
dd00: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
dd10: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
dd20: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
dd30: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
dd40: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
dd50: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
dd60: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
dd70: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
dd80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
dd90: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
dda0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
ddb0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
ddc0: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
ddd0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
dde0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ddf0: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
de00: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
de10: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
de20: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
de30: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
de40: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
de50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
de60: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
de70: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
de80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
de90: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
dea0: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
deb0: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
dec0: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
ded0: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
dee0: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
def0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
df00: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
df10: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
df20: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
df30: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
df40: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
df50: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
df60: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
df70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
df80: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
df90: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
dfa0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
dfb0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
dfc0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
dfd0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
dfe0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
dff0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e000: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
e010: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
e020: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
e030: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
e040: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e050: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
e060: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
e070: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e080: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
e090: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
e0a0: 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
e0b0: 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
e0c0: 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
e0d0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
e0e0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e0f0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
e100: 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
e110: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
e120: 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
e130: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e140: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
e150: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
e160: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e170: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
e180: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
e190: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
e1a0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e1b0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
e1c0: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
e1d0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
e1e0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
e1f0: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
e200: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
e210: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
e220: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e230: 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
e240: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
e250: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
e260: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
e270: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e280: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
e290: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
e2a0: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
e2b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
e2c0: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
e2d0: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
e2e0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
e2f0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e300: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
e310: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
e320: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
e330: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
e340: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
e350: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
e360: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
e370: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
e380: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
e390: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
e3a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e3b0: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
e3c0: 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
e3d0: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
e3e0: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
e3f0: 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
e400: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
e410: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
e420: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
e430: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
e440: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
e450: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
e460: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
e470: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
e480: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
e490: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
e4a0: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  mit()].**   <li>
e4b0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
e4c0: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
e4d0: 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
e4e0: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
e4f0: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
e500: 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
e510: 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
e520: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
e530: 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
e540: 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
e550: 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
e560: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
e570: 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
e580: 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
e590: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
e5a0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e5b0: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
e5c0: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
e5d0: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
e5e0: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
e5f0: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
e600: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
e610: 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
e620: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
e630: 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
e640: 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
e650: 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
e660: 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
e670: 63 68 20 74 68 65 20 73 63 72 61 63 68 20 61 6c  ch the scrach al
e680: 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
e690: 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
e6a0: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
e6b0: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
e6c0: 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
e6d0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
e6e0: 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
e6f0: 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65  ations (N).  The
e700: 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
e710: 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
e720: 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65  le of 16..** The
e730: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
e740: 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
e750: 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
e760: 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
e770: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
e780: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
e790: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
e7a0: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
e7b0: 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20  han two scratch 
e7c0: 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
e7d0: 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f  ad.  So.** N sho
e7e0: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77  uld be set to tw
e7f0: 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64  ice the expected
e800: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
e810: 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e  of threads..** ^
e820: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
e830: 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
e840: 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
e850: 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
e860: 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
e870: 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20  base page size. 
e880: 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
e890: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
e8a0: 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
e8b0: 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
e8c0: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
e8d0: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
e8e0: 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
e8f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
e900: 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
e910: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
e920: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
e930: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e940: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
e950: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
e960: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
e970: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
e980: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
e990: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
e9a0: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
e9b0: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
e9c0: 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
e9d0: 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
e9e0: 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20   implemenation. 
e9f0: 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
ea00: 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
ea10: 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
ea20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
ea30: 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
ea40: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
ea50: 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
ea60: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
ea70: 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e  IG_PCACHE option
ea80: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
ea90: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
eaa0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41  o this option: A
eab0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79   pointer to 8-by
eac0: 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65  te aligned.** me
ead0: 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
eae0: 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
eaf0: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
eb00: 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
eb10: 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
eb20: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
eb30: 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
eb40: 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
eb50: 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
eb60: 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
eb70: 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
eb80: 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65  8) plus a little
eb90: 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a   extra for each.
eba0: 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
ebb0: 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65   ^The page heade
ebc0: 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20  r size is 20 to 
ebd0: 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69  40 bytes dependi
ebe0: 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73  ng on.** the hos
ebf0: 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20  t architecture. 
ec00: 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
ec10: 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
ec20: 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
ec30: 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
ec40: 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
ec50: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
ec60: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
ec70: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
ec80: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
ec90: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
eca0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
ecb0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
ecc0: 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
ecd0: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
ece0: 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
ecf0: 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
ed00: 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
ed10: 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
ed20: 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
ed30: 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
ed40: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
ed50: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
ed60: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
ed70: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
ed80: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
ed90: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
eda0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
edb0: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
edc0: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
edd0: 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69  pace..** The poi
ede0: 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  nter in the firs
edf0: 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a  t argument must.
ee00: 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  ** be aligned to
ee10: 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
ee20: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
ee30: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
ee40: 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  Lite.** will be 
ee50: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
ee60: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
ee70: 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
ee80: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
ee90: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
eea0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
eeb0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
eec0: 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
eed0: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
eee0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
eef0: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
ef00: 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
ef10: 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
ef20: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
ef30: 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
ef40: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
ef50: 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
ef60: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
ef70: 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
ef80: 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
ef90: 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
efa0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
efb0: 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
efc0: 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
efd0: 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
efe0: 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
eff0: 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
f000: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
f010: 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
f020: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
f030: 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
f040: 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
f050: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
f060: 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
f070: 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
f080: 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
f090: 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
f0a0: 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
f0b0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
f0c0: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
f0d0: 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
f0e0: 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
f0f0: 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
f100: 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
f110: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
f120: 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
f130: 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
f140: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
f150: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
f160: 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
f170: 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
f180: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
f190: 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
f1a0: 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
f1b0: 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
f1c0: 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
f1d0: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
f1e0: 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
f1f0: 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
f200: 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
f210: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
f220: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
f230: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
f240: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
f250: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
f260: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
f270: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
f280: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
f290: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
f2a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
f2b0: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
f2c0: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
f2d0: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
f2e0: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
f2f0: 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
f300: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
f310: 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
f320: 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
f330: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
f340: 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
f350: 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
f360: 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
f370: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
f380: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
f390: 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
f3a0: 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
f3b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
f3c0: 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
f3d0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f3e0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
f3f0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
f400: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
f410: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
f420: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
f430: 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
f440: 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
f450: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
f460: 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
f470: 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
f480: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f490: 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
f4a0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
f4b0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f4c0: 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
f4d0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
f4e0: 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  R].</dd>.**.** <
f4f0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f500: 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
f510: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
f520: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
f530: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
f540: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
f550: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
f560: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
f570: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
f580: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
f590: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
f5a0: 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
f5b0: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
f5c0: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
f5d0: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
f5e0: 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
f5f0: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
f600: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
f610: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
f620: 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
f630: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
f640: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
f650: 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
f660: 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
f670: 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
f680: 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
f690: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
f6a0: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
f6b0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
f6c0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
f6d0: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
f6e0: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
f6f0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
f700: 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
f710: 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
f720: 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
f730: 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
f740: 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
f750: 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
f760: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
f770: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
f780: 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
f790: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
f7a0: 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
f7b0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
f7c0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
f7d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
f7e0: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
f7f0: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
f800: 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
f810: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
f820: 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a  ine the default.
f830: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
f840: 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f  tion for the loo
f850: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
f860: 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a  locator on each.
f870: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
f880: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66  nection].  The f
f890: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
f8a0: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
f8b0: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
f8c0: 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
f8d0: 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
f8e0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
f8f0: 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
f900: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
f910: 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
f920: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
f930: 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75   the.** <i>defau
f940: 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
f950: 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
f960: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
f970: 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74  ASIDE].** verb t
f980: 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
f990: 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
f9a0: 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
f9b0: 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
f9c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
f9d0: 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
f9e0: 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
f9f0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
fa00: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f  _CONFIG_PCACHE</
fa10: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
fa20: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
fa30: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
fa40: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
fa50: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73  nter to.** an [s
fa60: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
fa70: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
fa80: 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
fa90: 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
faa0: 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
fab0: 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
fac0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
fad0: 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
fae0: 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
faf0: 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
fb00: 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
fb10: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
fb20: 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
fb30: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
fb40: 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74  IG_GETPCACHE</dt
fb50: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
fb60: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
fb70: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
fb80: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
fb90: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
fba0: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
fbb0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ods] object.  SQ
fbc0: 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74  Lite copies of t
fbd0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61  he current.** pa
fbe0: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
fbf0: 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
fc00: 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
fc10: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
fc20: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
fc30: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
fc40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
fc50: 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
fc60: 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
fc70: 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
fc80: 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
fc90: 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
fca0: 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
fcb0: 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
fcc0: 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
fcd0: 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
fce0: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
fcf0: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
fd00: 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
fd10: 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
fd20: 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
fd30: 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
fd40: 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
fd50: 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
fd60: 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
fd70: 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
fd80: 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
fd90: 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
fda0: 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
fdb0: 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
fdc0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
fdd0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
fde0: 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
fdf0: 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
fe00: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
fe10: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
fe20: 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
fe30: 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
fe40: 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
fe50: 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
fe60: 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
fe70: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
fe80: 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
fe90: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
fea0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
feb0: 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
fec0: 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
fed0: 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
fee0: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
fef0: 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
ff00: 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
ff10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
ff20: 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
ff30: 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
ff40: 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
ff50: 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
ff60: 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
ff70: 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
ff80: 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
ff90: 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
ffa0: 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
ffb0: 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
ffc0: 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
ffd0: 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
ffe0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
fff0: 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
10000 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
10010 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
10020 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
10030 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
10040 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
10050 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
10060 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
10070 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
10080 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
10090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
100a0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
100b0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
100c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
100d0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
100e0 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
100f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10100 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
10110 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
10120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10130 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
10140 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
10150 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
10160 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10170 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
10180 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
10190 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
101a0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
101b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
101c0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
101d0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
101e0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
101f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
10200 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
10210 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
10220 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
10230 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10240 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
10250 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
10260 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
10270 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10280 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
10290 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
102a0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
102b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
102c0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
102d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
102e0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
102f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10300 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
10310 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
10320 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
10330 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
10340 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
10350 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
10360 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
10370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10380 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10390 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
103a0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
103b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
103c0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
103d0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
103e0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
103f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10400 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
10410 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
10420 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  che_methods* */.
10430 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10440 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
10450 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
10460 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   void* */../*.**
10470 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
10480 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
10490 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
104a0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
104b0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
104c0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
104d0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
104e0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
104f0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
10500 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
10510 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
10520 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10530 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
10540 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
10550 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10560 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
10570 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
10580 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
10590 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
105a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
105b0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
105c0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
105d0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
105e0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
105f0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
10600 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
10610 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
10620 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
10630 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
10640 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
10650 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
10660 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
10670 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
10680 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
10690 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
106a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
106b0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
106c0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
106d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
106e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
106f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
10700 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
10710 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
10720 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
10730 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
10740 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
10750 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
10760 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
10770 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
10780 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
10790 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
107a0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
107b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
107c0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
107d0 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
107e0 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62  r to an memory b
107f0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
10800 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
10810 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
10820 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
10830 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
10840 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
10850 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
10860 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
10870 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
10880 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
10890 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
108a0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
108b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
108c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
108d0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
108e0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
108f0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
10900 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
10910 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
10920 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
10930 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
10940 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
10950 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
10960 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
10970 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
10980 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
10990 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
109a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
109b0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
109c0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
109d0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
109e0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
109f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10a00 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
10a10 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10a20 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
10a30 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
10a40 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
10a50 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
10a60 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a   next smaller.**
10a70 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
10a80 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
10a90 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
10aa0 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  IDE]</dd>.**.** 
10ab0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
10ac0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
10ad0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30  _LOOKASIDE    10
10ae0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
10af0 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20   int */.../*.** 
10b00 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
10b10 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
10b20 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
10b30 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
10b40 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
10b50 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
10b60 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
10b70 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
10b80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
10b90 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
10ba0 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
10bb0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
10bc0 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
10bd0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
10be0 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
10bf0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
10c00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
10c10 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
10c20 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
10c30 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
10c40 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
10c50 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
10c60 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
10c70 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
10c80 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
10c90 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
10ca0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
10cb0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
10cc0 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
10cd0 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
10ce0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
10cf0 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
10d00 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
10d10 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
10d20 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
10d30 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
10d40 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
10d50 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
10d60 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
10d70 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
10d80 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
10d90 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
10da0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
10db0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
10dc0 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
10dd0 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
10de0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
10df0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
10e00 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
10e10 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
10e20 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
10e30 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
10e40 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
10e50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
10e60 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
10e70 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e  argument.  ^If n
10e80 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
10e90 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
10ea0 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
10eb0 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
10ec0 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
10ed0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
10ee0 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
10ef0 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
10f00 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
10f10 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
10f20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
10f30 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
10f40 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
10f50 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
10f60 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e  rigger is runnin
10f70 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
10f80 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
10f90 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
10fa0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
10fb0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76  s routine.** rev
10fc0 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
10fd0 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
10fe0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
10ff0 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  er fired.)^.**.*
11000 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
11010 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
11020 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
11030 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
11040 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
11050 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
11060 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
11070 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
11080 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
11090 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
110a0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
110b0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
110c0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
110d0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
110e0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
110f0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
11100 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
11110 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
11120 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
11130 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
11140 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
11150 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
11160 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
11170 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
11180 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
11190 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
111a0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
111b0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
111c0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
111d0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
111e0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
111f0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
11200 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
11210 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
11220 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
11230 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
11240 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
11250 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
11260 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
11270 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
11280 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
11290 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
112a0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
112b0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
112c0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
112d0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
112e0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
112f0 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
11300 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
11310 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
11320 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
11330 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
11340 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
11350 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
11360 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
11370 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
11380 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
11390 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
113a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
113b0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
113c0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
113d0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
113e0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
113f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
11400 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
11410 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
11420 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
11430 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
11440 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
11450 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
11460 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
11470 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
11480 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
11490 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
114a0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
114b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
114c0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
114d0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
114e0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
114f0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
11500 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
11510 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
11520 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
11530 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
11540 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
11550 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
11560 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
11570 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
11580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11590 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
115a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
115b0 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
115c0 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
115d0 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
115e0 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
115f0 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
11600 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
11610 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
11620 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
11630 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
11640 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
11650 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
11660 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
11670 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
11680 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
11690 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
116a0 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
116b0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
116c0 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
116d0 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
116e0 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
116f0 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
11700 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
11710 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
11720 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
11730 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
11740 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
11750 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
11760 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
11770 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
11780 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
11790 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
117a0 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
117b0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
117c0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
117d0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
117e0 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
117f0 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
11800 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
11810 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
11820 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
11830 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
11840 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
11850 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
11860 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
11870 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
11880 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
11890 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
118a0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
118b0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
118c0 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
118d0 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
118e0 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
118f0 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
11900 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
11910 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
11920 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
11930 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
11940 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
11950 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
11960 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
11970 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
11980 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
11990 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
119a0 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
119b0 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
119c0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
119d0 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
119e0 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
119f0 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
11a00 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
11a10 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
11a20 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
11a30 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
11a40 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
11a50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
11a60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
11a70 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
11a80 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
11a90 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
11aa0 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
11ab0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
11ac0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
11ad0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
11ae0 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
11af0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
11b00 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
11b10 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
11b20 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
11b30 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
11b40 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
11b50 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
11b60 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
11b70 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
11b80 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
11b90 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
11ba0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
11bb0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
11bc0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
11bd0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
11be0 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
11bf0 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
11c00 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
11c10 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
11c20 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
11c30 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
11c40 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
11c50 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
11c60 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
11c70 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
11c80 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
11c90 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
11ca0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
11cb0 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
11cc0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
11cd0 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
11ce0 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
11cf0 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
11d00 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
11d10 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
11d20 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
11d30 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
11d40 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
11d50 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
11d60 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
11d70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
11d80 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
11d90 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
11da0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
11db0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
11dc0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
11dd0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
11de0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
11df0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
11e00 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
11e10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11e20 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
11e30 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
11e40 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
11e50 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
11e60 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
11e70 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
11e80 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
11e90 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
11ea0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
11eb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
11ec0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
11ed0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
11ee0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
11ef0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
11f00 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
11f10 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
11f20 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
11f30 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
11f40 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
11f50 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
11f60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
11f70 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
11f80 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
11f90 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
11fa0 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
11fb0 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
11fc0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
11fd0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
11fe0 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
11ff0 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
12000 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
12010 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
12020 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
12030 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
12040 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
12050 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
12060 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
12070 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
12080 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
12090 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
120a0 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
120b0 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
120c0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
120d0 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
120e0 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
120f0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
12100 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
12110 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
12120 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
12130 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
12140 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
12150 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
12160 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
12170 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12180 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
12190 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
121a0 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
121b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
121c0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
121d0 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
121e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
121f0 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
12200 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
12210 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
12220 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
12230 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
12240 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
12250 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
12260 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
12270 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
12280 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
12290 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
122a0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
122b0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
122c0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
122d0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
122e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
122f0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
12300 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12310 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
12320 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
12330 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
12340 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
12350 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
12360 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12370 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
12380 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12390 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
123a0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
123b0 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
123c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
123d0 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
123e0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
123f0 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
12400 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
12410 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
12420 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
12430 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
12440 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
12450 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
12460 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
12470 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
12480 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
12490 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
124a0 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
124b0 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
124c0 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
124d0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
124e0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
124f0 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
12500 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
12510 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
12520 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
12530 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
12540 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
12550 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
12560 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
12570 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
12580 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
12590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
125a0 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
125b0 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
125c0 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
125d0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
125e0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
125f0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
12600 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
12610 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
12620 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
12630 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12640 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
12650 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
12660 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
12670 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
12680 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
12690 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
126a0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
126b0 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
126c0 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
126d0 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
126e0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
126f0 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
12700 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
12710 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
12720 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
12730 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
12740 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
12750 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
12760 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
12770 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
12780 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
12790 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
127a0 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
127b0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
127c0 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
127d0 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
127e0 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
127f0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
12800 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
12810 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12820 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
12830 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
12840 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
12850 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
12860 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
12870 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
12880 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
12890 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
128a0 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
128b0 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
128c0 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
128d0 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
128e0 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
128f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
12900 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
12910 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
12920 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
12930 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
12940 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
12950 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
12960 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
12970 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
12980 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
12990 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
129a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
129b0 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
129c0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
129d0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
129e0 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
129f0 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
12a00 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
12a10 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
12a20 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
12a30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
12a40 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
12a50 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
12a60 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
12a70 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
12a80 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
12a90 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
12aa0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
12ab0 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
12ac0 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
12ad0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
12ae0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
12af0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12b00 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
12b10 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
12b20 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
12b30 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
12b40 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
12b50 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
12b60 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
12b70 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
12b80 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
12b90 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
12ba0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
12bb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
12bc0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
12bd0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
12be0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
12bf0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
12c00 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
12c10 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
12c20 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
12c30 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
12c40 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
12c50 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
12c60 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
12c70 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
12c80 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
12c90 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
12ca0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
12cb0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
12cc0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
12cd0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
12ce0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
12cf0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
12d00 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
12d10 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
12d20 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
12d30 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
12d40 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
12d50 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
12d60 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
12d70 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
12d80 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
12d90 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
12da0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
12db0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
12dc0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
12dd0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
12de0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
12df0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
12e00 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
12e10 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
12e20 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
12e30 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
12e40 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
12e50 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
12e60 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
12e70 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
12e80 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
12e90 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
12ea0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
12eb0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
12ec0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
12ed0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
12ee0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
12ef0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
12f00 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
12f10 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
12f20 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
12f30 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
12f40 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
12f50 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12f60 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
12f70 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
12f80 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
12f90 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
12fa0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
12fb0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
12fc0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
12fd0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
12fe0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
12ff0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
13000 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
13010 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
13020 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
13030 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
13040 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
13050 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
13060 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
13070 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
13080 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
13090 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
130a0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
130b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
130c0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
130d0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
130e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
130f0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
13100 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
13110 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
13120 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
13130 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
13140 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
13150 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
13160 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
13170 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
13180 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
13190 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
131a0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
131b0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
131c0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
131d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
131e0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
131f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
13200 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
13210 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
13220 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
13230 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
13240 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
13250 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
13260 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
13270 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
13280 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
13290 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
132a0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
132b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
132c0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
132d0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
132e0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
132f0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
13300 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
13310 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
13320 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
13330 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
13340 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
13350 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
13360 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
13370 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
13380 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
13390 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
133a0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
133b0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
133c0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
133d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
133e0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
133f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
13400 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
13410 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
13420 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
13430 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
13440 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
13450 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
13460 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
13470 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13480 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
13490 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
134a0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
134b0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
134c0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
134d0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
134e0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
134f0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13500 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
13510 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
13520 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
13530 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
13540 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
13550 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
13560 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
13570 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
13580 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
13590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
135a0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
135b0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
135c0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
135d0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
135e0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
135f0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
13600 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
13610 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
13620 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
13630 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
13640 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
13650 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
13660 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
13670 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
13680 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
13690 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
136a0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
136b0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
136c0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
136d0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
136e0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
136f0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
13700 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
13710 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
13720 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
13730 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
13740 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
13750 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
13760 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
13770 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
13780 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
13790 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
137a0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
137b0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
137c0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
137d0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
137e0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
137f0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
13800 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
13810 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
13820 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
13830 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
13840 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
13850 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
13860 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
13870 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
13880 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
13890 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
138a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
138b0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
138c0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
138d0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
138e0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
138f0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
13900 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
13910 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
13920 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
13930 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
13940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
13950 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
13960 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
13970 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
13980 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
13990 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
139a0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
139b0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
139c0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
139d0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
139e0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
139f0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
13a00 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
13a10 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
13a20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
13a30 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
13a40 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
13a50 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
13a60 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
13a70 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
13a80 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
13a90 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
13aa0 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
13ab0 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
13ac0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
13ad0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
13ae0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
13af0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
13b00 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
13b10 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
13b20 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
13b30 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
13b40 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
13b50 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
13b60 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
13b70 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
13b80 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
13b90 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
13ba0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
13bb0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
13bc0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
13bd0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
13be0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
13bf0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
13c00 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
13c10 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
13c20 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
13c30 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
13c40 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
13c50 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
13c60 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
13c70 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
13c80 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
13c90 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
13ca0 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
13cb0 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
13cc0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
13cd0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
13ce0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
13cf0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
13d00 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
13d10 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
13d20 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
13d30 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
13d40 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
13d50 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
13d60 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
13d70 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
13d80 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
13d90 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
13da0 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
13db0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
13dc0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
13dd0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
13de0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
13df0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
13e00 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
13e10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13e20 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
13e30 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
13e40 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
13e50 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
13e60 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
13e70 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
13e80 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
13e90 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
13ea0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13eb0 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
13ec0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
13ed0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
13ee0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
13ef0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
13f00 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
13f10 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
13f20 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
13f30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
13f40 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
13f50 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
13f60 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
13f70 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13f80 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
13f90 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
13fa0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
13fb0 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
13fc0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
13fd0 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
13fe0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
13ff0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
14000 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
14010 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
14020 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
14030 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
14040 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
14050 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
14060 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
14070 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
14080 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
14090 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
140a0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
140b0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
140c0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
140d0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
140e0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
140f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
14100 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
14110 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
14120 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
14130 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
14140 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
14150 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
14160 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
14170 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
14180 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
14190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
141a0 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
141b0 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
141c0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
141d0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
141e0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
141f0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
14200 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
14210 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
14220 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
14230 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
14240 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
14250 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14260 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
14270 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
14280 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
14290 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
142a0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
142b0 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ries.**.** Defin
142c0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
142d0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
142e0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
142f0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
14300 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
14310 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
14320 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
14330 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
14340 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
14350 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
14360 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
14370 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
14380 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
14390 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
143a0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
143b0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
143c0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
143d0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
143e0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
143f0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
14400 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
14410 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
14420 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
14430 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
14440 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
14450 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
14460 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
14470 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
14480 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
14490 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
144a0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
144b0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
144c0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
144d0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
144e0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
144f0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
14500 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
14510 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
14520 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
14530 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
14540 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
14550 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
14560 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
14570 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
14580 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
14590 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
145a0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
145b0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
145c0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
145d0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
145e0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
145f0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
14600 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
14610 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
14620 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
14630 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
14640 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
14650 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
14660 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
14670 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
14680 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
14690 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
146a0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
146b0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
146c0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
146d0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
146e0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61  e()]..**.** As a
146f0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
14700 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
14710 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
14720 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
14730 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
14740 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14750 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
14760 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
14770 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
14780 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14790 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
147a0 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
147b0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
147c0 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
147d0 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
147e0 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
147f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
14800 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
14810 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
14820 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
14830 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
14840 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
14850 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
14860 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
14870 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
14880 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
14890 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
148a0 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
148b0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
148c0 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
148d0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
148e0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
148f0 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
14900 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
14910 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
14920 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
14930 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
14940 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
14950 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
14960 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
14970 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14980 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
14990 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
149a0 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
149b0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
149c0 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
149d0 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
149e0 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
149f0 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
14a00 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
14a10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
14a20 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
14a30 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
14a40 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
14a50 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
14a60 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
14a70 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
14a80 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
14a90 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
14aa0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
14ab0 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
14ac0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
14ad0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
14ae0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
14af0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
14b00 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
14b10 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
14b20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
14b30 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
14b40 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
14b50 73 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65 20  should pass the 
14b60 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
14b70 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
14b80 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
14b90 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
14ba0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
14bb0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
14bc0 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
14bd0 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
14be0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14bf0 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
14c00 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14c10 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
14c20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
14c30 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
14c40 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
14c50 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
14c60 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
14c70 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
14c80 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
14c90 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
14ca0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
14cb0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
14cc0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
14cd0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
14ce0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
14cf0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
14d00 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
14d10 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
14d20 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
14d30 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
14d40 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
14d50 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
14d60 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
14d70 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
14d80 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
14d90 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
14da0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
14db0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
14dc0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
14dd0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
14de0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
14df0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
14e00 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
14e10 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
14e20 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
14e30 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
14e40 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
14e50 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
14e60 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e 0a  e3_errmsg()].)^.
14e70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
14e80 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
14e90 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
14ea0 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
14eb0 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
14ec0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
14ed0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
14ee0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
14ef0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
14f00 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
14f10 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
14f20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
14f30 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
14f40 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
14f50 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
14f60 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
14f70 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
14f80 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
14f90 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
14fa0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
14fb0 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
14fc0 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
14fd0 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
14fe0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
14ff0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
15000 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15010 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
15020 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
15030 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
15040 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
15050 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
15060 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
15070 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
15080 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
15090 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
150a0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
150b0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
150c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
150d0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
150e0 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
150f0 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
15100 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
15110 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15120 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
15130 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
15140 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
15150 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
15160 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
15170 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
15180 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
15190 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
151a0 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
151b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
151c0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
151d0 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
151e0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
151f0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
15200 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c  ..**.** ^(In sql
15210 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
15220 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
15230 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
15240 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
15250 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
15260 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
15270 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
15280 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
15290 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
152a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
152b0 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
152c0 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
152d0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
152e0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
152f0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
15300 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
15310 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
15320 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
15330 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
15340 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
15350 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
15360 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
15370 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
15380 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
15390 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
153a0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
153b0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
153c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
153d0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
153e0 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
153f0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
15400 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
15410 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
15420 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
15430 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
15440 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
15450 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
15460 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
15470 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
15480 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
15490 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
154a0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
154b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
154c0 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
154d0 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
154e0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
154f0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
15500 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
15510 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
15520 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
15530 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
15540 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
15550 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
15560 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
15570 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
15580 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
15590 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
155a0 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
155b0 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
155c0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
155d0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
155e0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
155f0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
15600 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
15610 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
15620 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ers..**.** These
15630 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
15640 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
15650 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
15660 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
15670 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
15680 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
15690 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
156a0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
156b0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
156c0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
156d0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
156e0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
156f0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
15700 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
15710 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
15720 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
15730 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
15740 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
15750 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ull-terminated.*
15760 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
15770 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
15780 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
15790 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
157a0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
157b0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
157c0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
157d0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
157e0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
157f0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
15800 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
15810 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
15820 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
15830 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
15840 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
15850 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
15860 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
15870 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
15880 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
15890 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
158a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
158b0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
158c0 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
158d0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
158e0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
158f0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
15900 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
15910 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
15920 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
15930 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15940 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
15950 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
15960 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
15970 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
15980 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
15990 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
159a0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
159b0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
159c0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
159d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
159e0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
159f0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
15a00 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
15a10 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
15a20 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
15a30 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
15a40 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
15a50 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
15a60 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15a70 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
15a80 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
15a90 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
15aa0 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
15ab0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
15ac0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
15ad0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
15ae0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
15af0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
15b00 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
15b10 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
15b20 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
15b30 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
15b40 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
15b50 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
15b60 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
15b70 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
15b80 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
15b90 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
15ba0 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
15bb0 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
15bc0 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
15bd0 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
15be0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
15bf0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
15c00 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
15c10 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
15c20 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
15c30 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
15c40 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
15c50 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
15c60 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
15c70 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
15c80 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
15c90 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
15ca0 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
15cb0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
15cc0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
15cd0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
15ce0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
15cf0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
15d00 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
15d10 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
15d20 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
15d30 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
15d40 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
15d50 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15d60 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
15d70 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
15d80 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
15d90 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
15da0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
15db0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
15dc0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
15dd0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
15de0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
15df0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
15e00 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
15e10 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
15e20 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
15e30 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
15e40 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
15e50 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
15e60 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
15e70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
15e80 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
15e90 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
15ea0 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
15eb0 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
15ec0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
15ed0 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
15ee0 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
15ef0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
15f00 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
15f10 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
15f20 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
15f30 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
15f40 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
15f50 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
15f60 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
15f70 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
15f80 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
15f90 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
15fa0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
15fb0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
15fc0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
15fd0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
15fe0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
15ff0 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
16000 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
16010 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
16020 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
16030 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
16040 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
16050 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
16060 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
16070 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
16080 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
16090 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
160a0 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
160b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
160c0 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
160d0 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
160e0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
160f0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
16100 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
16110 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
16120 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
16130 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16140 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
16150 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
16160 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
16170 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
16180 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
16190 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
161a0 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
161b0 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
161c0 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
161d0 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
161e0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
161f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
16200 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
16210 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
16220 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
16230 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
16240 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
16250 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
16260 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
16270 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
16280 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
16290 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
162a0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
162b0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
162c0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
162d0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
162e0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
162f0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
16300 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
16310 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
16320 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
16330 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
16340 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
16350 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
16360 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
16370 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
16380 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
16390 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
163a0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
163b0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
163c0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
163d0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
163e0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
163f0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
16400 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
16410 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
16420 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
16430 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
16440 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
16450 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
16460 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
16470 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
16480 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
16490 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
164a0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
164b0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
164c0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
164d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
164e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
164f0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  loc()..**.** ^(T
16500 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
16510 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
16520 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
16530 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
16540 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
16550 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
16560 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
16570 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
16580 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
16590 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
165a0 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
165b0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
165c0 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49  parameter.)^ ^ I
165d0 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
165e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
165f0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
16600 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
16610 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
16620 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
16630 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
16640 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
16650 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
16660 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16670 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
16680 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  c()..** ^If the 
16690 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
166a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
166b0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
166c0 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
166d0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
166e0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
166f0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
16700 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
16710 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
16720 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
16730 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
16740 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  oc()..** ^sqlite
16750 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
16760 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
16770 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
16780 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
16790 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
167a0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
167b0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
167c0 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
167d0 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
167e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
167f0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
16800 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
16810 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
16820 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
16830 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
16840 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
16850 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
16860 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
16870 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
16880 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
16890 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
168a0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
168b0 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
168c0 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
168d0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
168e0 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
168f0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
16900 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
16910 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
16920 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16930 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
16940 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
16950 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
16960 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  dary..**.** In S
16970 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
16980 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
16990 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
169a0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
169b0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
169c0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
169d0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
169e0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
169f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
16a00 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
16a10 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
16a20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
16a30 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
16a40 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
16a50 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
16a60 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
16a70 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  be used..**.** T
16a80 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
16a90 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
16aa0 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  lls.** the syste
16ab0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
16ac0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
16ad0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
16ae0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
16af0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
16b00 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
16b10 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
16b20 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
16b30 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
16b40 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
16b50 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
16b60 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
16b70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
16b80 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65  rors are detecte
16b90 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61  d, but.** they a
16ba0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
16bb0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
16bc0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
16bd0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
16be0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
16bf0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
16c00 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
16c10 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
16c20 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
16c30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
16c40 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
16c50 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
16c60 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
16c70 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
16c80 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
16c90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16ca0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
16cb0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
16cc0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
16cd0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
16ce0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
16cf0 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
16d00 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
16d10 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
16d20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
16d30 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
16d40 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
16d50 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
16d60 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
16d70 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
16d80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
16d90 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
16da0 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
16db0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
16dc0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
16dd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16de0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
16df0 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
16e00 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
16e10 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
16e20 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
16e30 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
16e40 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
16e50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16e60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
16e70 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
16e80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
16e90 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
16ea0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
16eb0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
16ec0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
16ed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
16ee0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
16ef0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
16f00 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
16f10 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
16f20 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
16f30 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
16f40 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
16f50 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
16f60 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
16f70 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
16f80 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
16f90 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
16fa0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16fb0 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
16fc0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
16fd0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
16fe0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
16ff0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
17000 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
17010 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
17020 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
17030 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
17040 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
17050 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
17060 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
17070 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
17080 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
17090 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
170a0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
170b0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
170c0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
170d0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
170e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
170f0 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
17100 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
17110 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
17120 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
17130 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
17140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
17150 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
17160 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
17170 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
17180 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
17190 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
171a0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
171b0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
171c0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
171d0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
171e0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
171f0 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
17200 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
17210 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
17220 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
17230 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
17240 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
17250 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
17260 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
17270 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
17280 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
17290 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
172a0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
172b0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
172c0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
172d0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
172e0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
172f0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
17300 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
17310 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
17320 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
17330 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
17340 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
17350 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
17360 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
17370 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
17380 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
17390 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
173a0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
173b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
173c0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
173d0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
173e0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
173f0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
17400 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
17410 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
17420 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
17430 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
17440 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
17450 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
17460 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
17470 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
17480 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
17490 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
174a0 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
174b0 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
174c0 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
174d0 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
174e0 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
174f0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
17500 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
17510 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
17520 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f  s] object..** ^O
17530 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
17540 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
17550 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
17560 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
17570 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
17580 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
17590 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
175a0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
175b0 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
175c0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
175d0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
175e0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
175f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
17600 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
17610 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
17620 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
17630 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
17640 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  a authorizer cal
17650 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
17660 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
17670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17680 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
17690 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
176a0 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
176b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
176c0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
176d0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
176e0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
176f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
17700 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
17710 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
17720 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
17730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
17740 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
17750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
17760 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
17770 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
17780 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
17790 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
177a0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
177b0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
177c0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
177d0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
177e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
177f0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
17800 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
17810 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
17820 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
17830 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
17840 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
17850 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
17860 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
17870 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
17880 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
17890 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
178a0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
178b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
178c0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
178d0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
178e0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
178f0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
17900 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
17910 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
17920 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
17930 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
17940 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
17950 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
17960 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
17970 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
17980 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
17990 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
179a0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
179b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
179c0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
179d0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
179e0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
179f0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
17a00 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
17a10 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
17a20 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
17a30 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
17a40 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
17a50 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
17a60 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
17a70 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
17a80 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
17a90 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
17aa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17ab0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
17ac0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
17ad0 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
17ae0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
17af0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
17b00 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
17b10 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
17b20 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
17b30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
17b40 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
17b50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
17b60 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
17b70 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
17b80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17b90 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
17ba0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
17bb0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
17bc0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
17bd0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
17be0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
17bf0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
17c00 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
17c10 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
17c20 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
17c30 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
17c40 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
17c50 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
17c60 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
17c70 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
17c80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
17c90 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
17ca0 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
17cb0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
17cc0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
17cd0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
17ce0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
17cf0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
17d00 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
17d10 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
17d20 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
17d30 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
17d40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
17d50 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
17d60 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
17d70 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
17d80 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
17d90 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
17da0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
17db0 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
17dc0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
17dd0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
17de0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
17df0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
17e00 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
17e10 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
17e20 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
17e30 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
17e40 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
17e50 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
17e60 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
17e70 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
17e80 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
17e90 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
17ea0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
17eb0 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
17ec0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
17ed0 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
17ee0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
17ef0 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
17f00 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
17f10 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
17f20 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
17f30 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
17f40 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
17f50 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
17f60 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
17f70 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
17f80 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
17f90 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
17fa0 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
17fb0 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
17fc0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
17fd0 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
17fe0 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
17ff0 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
18000 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
18010 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
18020 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
18030 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
18040 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
18050 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
18060 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
18070 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
18080 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
18090 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
180a0 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
180b0 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
180c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
180d0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
180e0 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
180f0 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
18100 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
18110 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
18120 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
18130 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
18140 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
18150 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
18160 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
18170 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
18180 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
18190 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
181a0 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
181b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
181c0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
181d0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
181e0 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
181f0 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
18200 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
18210 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
18220 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
18230 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
18240 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
18250 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
18260 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
18270 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
18280 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
18290 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
182a0 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
182b0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
182c0 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
182d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
182e0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
182f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18300 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
18310 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
18320 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18330 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
18340 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
18350 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
18360 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
18370 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
18380 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
18390 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
183a0 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
183b0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
183c0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
183d0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
183e0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
183f0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
18400 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18410 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
18420 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
18430 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
18440 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
18450 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18460 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18470 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
18480 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
18490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
184a0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
184b0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
184c0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
184d0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
184e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
184f0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
18500 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
18510 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
18520 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
18530 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
18540 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18550 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
18560 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
18570 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
18580 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
18590 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
185a0 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
185b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
185c0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
185d0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
185e0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
185f0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
18600 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18610 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
18620 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
18630 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
18640 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
18650 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
18660 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
18670 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
18680 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
18690 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
186a0 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
186b0 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
186c0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
186d0 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
186e0 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
186f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
18700 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
18710 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
18720 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
18730 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
18740 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18750 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
18760 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
18770 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
18780 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
18790 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
187a0 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
187b0 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
187c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
187d0 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
187e0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
187f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
18800 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
18810 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18820 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
18830 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
18840 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
18850 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
18860 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
18870 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
18880 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
18890 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
188a0 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
188b0 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
188c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
188d0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
188e0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
188f0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
18900 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
18910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18920 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
18930 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
18940 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
18950 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
18960 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
18970 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
18980 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
18990 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
189a0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
189b0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
189c0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
189d0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
189e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
189f0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
18a00 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
18a10 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
18a20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
18a30 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
18a40 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
18a50 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
18a60 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
18a70 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
18a80 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
18a90 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
18aa0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
18ab0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
18ac0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
18ad0 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
18ae0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
18af0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
18b00 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
18b10 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
18b20 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
18b30 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
18b40 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
18b50 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
18b60 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
18b70 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
18b80 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
18b90 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
18ba0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
18bb0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
18bc0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
18bd0 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
18be0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
18bf0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
18c00 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
18c10 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
18c20 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
18c30 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
18c40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
18c50 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
18c60 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
18c70 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
18c80 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
18c90 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
18ca0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
18cb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18cc0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
18cd0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
18ce0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
18cf0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
18d00 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
18d10 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
18d20 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
18d30 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
18d40 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
18d50 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
18d60 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
18d70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18d80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18d90 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
18da0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
18db0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
18dc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18dd0 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
18de0 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
18df0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
18e00 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
18e10 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18e20 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
18e30 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
18e40 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
18e50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18e60 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18e70 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
18e80 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
18e90 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
18ea0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18eb0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18ec0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
18ed0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18ee0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18ef0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18f00 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
18f10 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
18f20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
18f30 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
18f40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18f50 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
18f60 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
18f70 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
18f80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18f90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18fa0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
18fb0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
18fc0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
18fd0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18fe0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18ff0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
19000 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
19010 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
19020 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19030 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19040 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
19050 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
19060 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19070 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19080 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19090 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
190a0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
190b0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
190c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
190d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
190e0 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
190f0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
19100 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
19110 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19120 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19130 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
19140 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
19150 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
19160 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
19170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19180 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
19190 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
191a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
191b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
191c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
191d0 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
191e0 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
191f0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
19200 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19210 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
19220 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
19230 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
19240 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
19250 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19260 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
19270 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
19280 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
19290 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
192a0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
192b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
192c0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
192d0 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
192e0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
192f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19300 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
19310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
19320 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
19330 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
19340 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19350 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
19360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
19370 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
19380 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
19390 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
193a0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
193b0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
193c0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
193d0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
193e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
193f0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
19400 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
19410 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
19420 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19430 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19440 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
19450 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
19460 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
19470 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19480 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19490 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
194a0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
194b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
194c0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
194d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
194e0 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
194f0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
19500 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
19510 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19520 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19530 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
19540 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
19550 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
19560 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19580 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
19590 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
195a0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
195b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
195c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
195d0 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
195e0 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
195f0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
19600 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19610 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19620 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
19630 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
19640 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
19650 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19660 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19670 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
19680 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
19690 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
196a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
196b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
196c0 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
196d0 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
196e0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
196f0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
19700 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
19710 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
19720 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
19730 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
19740 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
19750 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
19760 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
19770 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
19780 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
19790 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
197a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
197b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
197c0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
197d0 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
197e0 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
197f0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
19800 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
19810 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
19820 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
19830 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
19840 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
19850 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
19860 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
19870 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
19880 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
19890 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
198a0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
198b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
198c0 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
198d0 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
198e0 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
198f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
19900 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
19910 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
19920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
19930 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
19940 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
19950 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
19960 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
19970 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
19980 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
19990 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
199a0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
199b0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
199c0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
199d0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
199e0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
199f0 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
19a00 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
19a10 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
19a20 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
19a30 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
19a40 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
19a50 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
19a60 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ^.**.** ^The cal
19a70 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
19a80 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
19a90 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
19aa0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
19ab0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
19ac0 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
19ad0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
19ae0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
19af0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
19b00 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
19b10 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
19b20 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
19b30 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
19b40 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
19b50 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
19b60 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
19b70 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
19b80 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
19b90 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
19ba0 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
19bb0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
19bc0 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
19bd0 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
19be0 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
19bf0 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
19c00 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
19c10 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
19c20 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
19c30 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
19c40 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
19c50 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
19c60 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
19c70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
19c80 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
19c90 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
19ca0 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
19cb0 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
19cc0 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
19cd0 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
19ce0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
19cf0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69  f SQLite..*/.voi
19d00 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
19d10 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
19d20 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
19d30 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
19d40 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
19d50 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
19d60 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
19d70 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
19d80 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
19d90 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
19da0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
19db0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
19dc0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
19dd0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
19de0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
19df0 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20  tine configures 
19e00 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
19e10 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f  ion - the.** pro
19e20 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d  gress callback -
19e30 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
19e40 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
19e50 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e  ring long.** run
19e60 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ning calls to [s
19e70 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
19e80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19e90 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
19ea0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20  _get_table()].  
19eb0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
19ec0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
19ed0 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
19ee0 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
19ef0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
19f00 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ry..**.** ^If th
19f10 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
19f20 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
19f30 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
19f40 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
19f50 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
19f60 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
19f70 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
19f80 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
19f90 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
19fa0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
19fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
19fc0 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  ess handler must
19fd0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
19fe0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
19ff0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1a000 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1a010 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
1a020 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1a030 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1a040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1a050 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1a060 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1a070 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1a080 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a090 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1a0a0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1a0b0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1a0c0 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
1a0d0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1a0e0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
1a0f0 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
1a100 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
1a110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
1a120 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
1a130 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
1a140 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1a150 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
1a160 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
1a170 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20  e whose name is 
1a180 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20  given by the.** 
1a190 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1a1a0 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
1a1b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1a1c0 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1a1d0 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
1a1e0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1a1f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
1a200 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
1a210 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
1a220 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
1a230 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
1a240 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
1a250 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
1a260 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
1a270 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
1a280 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
1a290 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
1a2a0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
1a2b0 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
1a2c0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
1a2d0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
1a2e0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
1a2f0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
1a300 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
1a310 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
1a320 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
1a330 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1a340 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
1a350 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
1a360 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1a370 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
1a380 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
1a390 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
1a3a0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
1a3b0 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
1a3c0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1a3d0 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
1a3e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1a3f0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
1a400 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
1a410 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
1a420 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
1a430 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
1a440 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
1a450 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
1a460 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
1a470 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
1a480 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1a490 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1a4a0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
1a4b0 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
1a4c0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1a4d0 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
1a4e0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1a4f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1a500 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
1a510 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1a520 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1a530 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
1a540 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
1a550 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
1a560 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
1a570 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
1a580 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
1a590 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
1a5a0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
1a5b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1a5c0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
1a5d0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
1a5e0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
1a5f0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
1a600 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
1a610 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
1a620 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
1a630 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
1a640 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
1a650 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
1a660 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
1a670 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
1a680 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
1a690 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
1a6a0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
1a6b0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1a6c0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
1a6d0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
1a6e0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
1a6f0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
1a700 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
1a710 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
1a720 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
1a730 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1a740 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
1a750 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1a760 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
1a770 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
1a780 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1a790 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  CHE],.** and/or 
1a7a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
1a7b0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73  VATECACHE] flags
1a7c0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
1a7d0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1a7e0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
1a7f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1a800 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1a810 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
1a820 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
1a830 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1a840 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
1a850 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1a860 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
1a870 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1a880 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1a890 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1a8a0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1a8b0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1a8c0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1a8d0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
1a8e0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
1a8f0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
1a900 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
1a910 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1a920 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
1a930 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
1a940 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
1a950 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
1a960 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
1a970 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1a980 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1a990 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1a9a0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
1a9b0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
1a9c0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1a9d0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1a9e0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
1a9f0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
1aa00 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69  eates it if.** i
1aa10 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
1aa20 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
1aa30 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
1aa40 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
1aa50 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
1aa60 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1aa70 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
1aa80 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
1aa90 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
1aaa0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1aab0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1aac0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
1aad0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
1aae0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20   shown above or 
1aaf0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69  one of the combi
1ab00 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1ab10 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20  ove combined.** 
1ab20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
1ab30 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
1ab40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1ab50 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c  LMUTEX],.** [SQL
1ab60 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1ab70 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51  ACHE] and/or [SQ
1ab80 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1ab90 45 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a  ECACHE] flags,.*
1aba0 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1abb0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1abc0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1abd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1abe0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1abf0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1ac00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1ac10 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1ac20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1ac30 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1ac40 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1ac50 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1ac60 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1ac70 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1ac80 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1ac90 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1aca0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1acb0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1acc0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1acd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1ace0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1acf0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1ad00 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1ad10 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1ad20 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1ad30 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1ad40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1ad50 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1ad60 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1ad70 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1ad80 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1ad90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ada0 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1adb0 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1adc0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1add0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1ade0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1adf0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1ae00 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1ae10 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1ae20 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1ae30 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1ae40 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1ae50 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1ae60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ae70 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1ae80 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1ae90 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1aea0 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1aeb0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1aec0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1aed0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1aee0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1aef0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1af00 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1af10 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1af20 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1af30 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
1af40 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
1af50 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
1af60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1af70 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
1af80 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1af90 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1afa0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
1afb0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
1afc0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
1afd0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
1afe0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
1aff0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
1b000 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
1b010 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
1b020 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
1b030 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
1b040 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
1b050 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
1b060 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
1b070 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
1b080 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
1b090 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
1b0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b0b0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
1b0c0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1b0d0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1b0e0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
1b0f0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
1b100 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
1b110 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
1b120 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
1b130 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
1b140 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
1b150 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b160 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1b170 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
1b180 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1b190 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1b1a0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1b1b0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1b1c0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1b1d0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1b1e0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1b1f0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1b200 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1b210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1b220 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
1b230 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1b240 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1b250 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1b260 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1b270 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1b280 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1b290 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1b2a0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1b2b0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1b2c0 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1b2d0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1b2e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1b2f0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1b300 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1b310 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1b320 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1b330 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1b340 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1b350 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1b360 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1b370 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1b380 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1b390 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1b3a0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1b3b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1b3c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b3d0 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
1b3e0 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1b3f0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1b400 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1b410 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1b420 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1b430 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1b440 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1b450 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1b460 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1b470 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1b480 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1b490 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1b4a0 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1b4b0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1b4c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1b4d0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1b4e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1b4f0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1b500 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1b510 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1b520 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1b530 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1b540 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1b550 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1b560 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1b570 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1b580 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1b590 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1b5a0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1b5b0 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1b5c0 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1b5d0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1b5e0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1b5f0 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1b600 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1b610 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1b620 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1b630 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1b640 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1b650 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1b660 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1b670 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1b680 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1b690 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1b6a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b6b0 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1b6c0 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1b6d0 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1b6e0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1b6f0 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1b700 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1b710 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1b720 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1b730 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1b740 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1b750 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1b760 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1b770 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1b780 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1b790 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1b7a0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1b7b0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1b7c0 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1b7d0 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1b7e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1b7f0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1b800 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1b810 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1b820 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1b830 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1b840 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1b850 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1b860 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1b870 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1b880 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1b890 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1b8a0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1b8b0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1b8c0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1b8d0 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1b8e0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1b8f0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1b900 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1b910 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1b920 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1b930 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1b940 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1b950 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1b960 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1b970 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1b980 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1b990 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1b9a0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1b9b0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1b9c0 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1b9d0 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1b9e0 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1b9f0 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1ba00 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1ba10 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1ba20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1ba30 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1ba40 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1ba50 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
1ba60 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
1ba70 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
1ba80 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
1ba90 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
1baa0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1bab0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
1bac0 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
1bad0 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
1bae0 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
1baf0 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1bb00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1bb10 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
1bb20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
1bb30 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
1bb40 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
1bb50 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
1bb60 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
1bb70 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1bb80 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
1bb90 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1bba0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
1bbb0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
1bbc0 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
1bbd0 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
1bbe0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
1bbf0 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1bc00 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1bc10 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1bc20 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1bc30 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1bc40 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1bc50 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1bc60 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
1bc70 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
1bc80 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
1bc90 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
1bca0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1bcb0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1bcc0 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
1bcd0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1bce0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1bcf0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1bd00 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
1bd10 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
1bd20 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1bd30 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
1bd40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1bd50 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
1bd60 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1bd70 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1bd80 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
1bd90 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
1bda0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
1bdb0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
1bdc0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
1bdd0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1bde0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
1bdf0 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
1be00 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
1be10 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
1be20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
1be30 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
1be40 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
1be50 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
1be60 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
1be70 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
1be80 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
1be90 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
1bea0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
1beb0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
1bec0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1bed0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
1bee0 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
1bef0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
1bf00 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
1bf10 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
1bf20 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
1bf30 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
1bf40 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
1bf50 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
1bf60 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
1bf70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bf80 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1bf90 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
1bfa0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1bfb0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
1bfc0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
1bfd0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
1bfe0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
1bff0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
1c000 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
1c010 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
1c020 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1c030 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
1c040 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
1c050 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
1c060 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
1c070 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
1c080 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1c090 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1c0a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1c0b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
1c0c0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
1c0d0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
1c0e0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
1c0f0 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
1c100 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
1c110 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
1c120 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
1c130 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
1c140 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
1c150 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
1c160 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1c170 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
1c180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c190 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
1c1a0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
1c1b0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
1c1c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1c1d0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
1c1e0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1c1f0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
1c200 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
1c210 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
1c220 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
1c230 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1c240 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
1c250 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
1c260 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e  struct.  The fun
1c270 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1c280 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a  e old limit.)^.*
1c290 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
1c2a0 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1c2b0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1c2c0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1c2d0 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68  ged..** ^(For th
1c2e0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  e limit category
1c2f0 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54   of SQLITE_LIMIT
1c300 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20  _XYZ there is a 
1c310 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
1c320 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
1c330 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70  ** set by a comp
1c340 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72  ile-time C prepr
1c350 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61  ocessor macro na
1c360 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  med .** [limits 
1c370 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a  | SQLITE_MAX_XYZ
1c380 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
1c390 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1c3a0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1c3b0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
1c3c0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1c3d0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1c3e0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1c3f0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1c400 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1c410 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1c420 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
1c430 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
1c440 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
1c450 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
1c460 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
1c470 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
1c480 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
1c490 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
1c4a0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
1c4b0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
1c4c0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
1c4d0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
1c4e0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
1c4f0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
1c500 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
1c510 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
1c520 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
1c530 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
1c540 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
1c550 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
1c560 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
1c570 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
1c580 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
1c590 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
1c5a0 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
1c5b0 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
1c5c0 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
1c5d0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
1c5e0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
1c5f0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
1c600 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
1c610 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
1c620 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
1c630 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
1c640 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
1c650 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
1c660 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
1c670 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
1c680 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
1c690 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1c6a0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
1c6b0 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
1c6c0 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
1c6d0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
1c6e0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
1c6f0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
1c700 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
1c710 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
1c720 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
1c730 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1c740 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
1c750 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
1c760 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
1c770 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
1c780 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
1c790 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
1c7a0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
1c7b0 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
1c7c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c7d0 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
1c7e0 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
1c7f0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
1c800 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
1c810 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
1c820 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
1c830 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
1c840 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
1c850 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
1c860 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
1c870 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
1c880 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
1c890 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
1c8a0 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
1c8b0 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
1c8c0 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
1c8d0 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
1c8e0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
1c8f0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
1c900 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
1c910 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
1c920 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
1c930 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
1c940 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1c950 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
1c960 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
1c970 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
1c980 20 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a   row.<dd>)^.**.*
1c990 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1c9a0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
1c9b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c9c0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1c9d0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
1c9e0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
1c9f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1ca00 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1ca10 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
1ca20 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1ca30 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1ca40 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
1ca50 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
1ca60 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
1ca70 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
1ca80 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1ca90 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1caa0 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
1cab0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
1cac0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
1cad0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1cae0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1caf0 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
1cb00 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1cb10 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
1cb20 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
1cb30 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
1cb40 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1cb50 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1cb60 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
1cb70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1cb80 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1cb90 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
1cba0 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
1cbb0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
1cbc0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1cbd0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
1cbe0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1cbf0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1cc00 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
1cc10 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
1cc20 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
1cc30 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1cc40 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1cc50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1cc60 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1cc70 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
1cc80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1cc90 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1cca0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
1ccb0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
1ccc0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1ccd0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1cce0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
1ccf0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1cd00 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
1cd10 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1cd20 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
1cd30 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1cd40 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1cd50 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1cd60 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1cd70 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
1cd80 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
1cd90 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
1cda0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
1cdb0 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
1cdc0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1cdd0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1cde0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
1cdf0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1ce00 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73  ber of variables
1ce10 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1ce20 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a  ment that can.**
1ce30 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29   be bound.</dd>)
1ce40 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1ce50 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
1ce60 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
1ce70 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1ce80 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
1ce90 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
1cea0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1ceb0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1cec0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1ced0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1cee0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
1cef0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1cf00 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1cf10 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
1cf20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1cf30 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
1cf40 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
1cf50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1cf60 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1cf70 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
1cf80 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1cf90 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
1cfa0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
1cfb0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
1cfc0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
1cfd0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
1cfe0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1cff0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
1d000 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
1d010 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d020 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
1d030 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
1d040 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d050 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1d060 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
1d070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d080 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1d090 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
1d0a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1d0b0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
1d0c0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
1d0d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d0e0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
1d0f0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
1d100 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
1d110 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1d120 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
1d130 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
1d140 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
1d150 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
1d160 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
1d170 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
1d180 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1d190 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1d1a0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
1d1b0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
1d1c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
1d1d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
1d1e0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
1d1f0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1d200 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1d210 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1d220 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1d230 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
1d240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d250 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
1d260 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
1d270 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1d280 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
1d290 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
1d2a0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
1d2b0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
1d2c0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1d2d0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
1d2e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1d2f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1d300 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
1d310 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
1d320 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
1d330 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
1d340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1d350 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
1d360 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
1d370 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1d380 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1d390 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
1d3a0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
1d3b0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
1d3c0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
1d3d0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1d3e0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
1d3f0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
1d400 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
1d410 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
1d420 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
1d430 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1d440 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
1d450 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
1d460 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
1d470 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
1d480 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
1d490 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
1d4a0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
1d4b0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
1d4c0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
1d4d0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
1d4e0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
1d4f0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
1d500 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
1d510 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
1d520 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
1d530 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
1d540 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
1d550 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
1d560 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
1d570 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1d580 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
1d590 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
1d5a0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
1d5b0 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a  inator bytes..**
1d5c0 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
1d5d0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
1d5e0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1d5f0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
1d600 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
1d610 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1d620 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1d630 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
1d640 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1d650 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
1d660 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
1d670 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
1d680 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
1d690 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
1d6a0 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
1d6b0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
1d6c0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
1d6d0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
1d6e0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
1d6f0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
1d700 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
1d710 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1d720 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
1d730 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
1d740 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
1d750 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
1d760 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
1d770 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1d780 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
1d790 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
1d7a0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
1d7b0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
1d7c0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
1d7d0 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
1d7e0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1d7f0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1d800 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
1d810 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
1d820 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1d830 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
1d840 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
1d850 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
1d860 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
1d870 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
1d880 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
1d890 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1d8a0 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
1d8b0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
1d8c0 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
1d8d0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1d8e0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1d8f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1d900 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d910 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1d920 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1d930 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1d940 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1d950 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1d960 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1d970 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1d980 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1d990 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1d9a0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1d9b0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1d9c0 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
1d9d0 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1d9e0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1d9f0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1da00 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1da10 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1da20 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1da30 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
1da40 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1da50 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
1da60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1da70 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1da80 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
1da90 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
1daa0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1dab0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
1dac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1dad0 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
1dae0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
1daf0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
1db00 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
1db10 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
1db20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1db30 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
1db40 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
1db50 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1db60 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
1db70 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49 66 20   it again.  ^If 
1db80 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
1db90 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
1dba0 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
1dbb0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
1dbc0 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
1dbd0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1dbe0 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
1dbf0 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
1dc00 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
1dc10 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
1dc20 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
1dc30 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
1dc40 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
1dc50 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1dc60 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
1dc70 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
1dc80 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
1dc90 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
1dca0 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
1dcb0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
1dcc0 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
1dcd0 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
1dce0 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
1dcf0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1dd00 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
1dd10 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1dd20 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
1dd30 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
1dd40 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
1dd50 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
1dd60 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
1dd70 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
1dd80 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
1dd90 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
1dda0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
1ddb0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
1ddc0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
1ddd0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
1dde0 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
1ddf0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
1de00 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
1de10 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
1de20 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1de30 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1de40 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
1de50 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
1de60 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1de70 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1de80 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1de90 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1dea0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1deb0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1dec0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1ded0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1dee0 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1def0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
1df00 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61  f the value of a
1df10 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
1df20 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
1df30 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
1df40 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67  e might.** chang
1df50 65 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e  e the query plan
1df60 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
1df70 2c 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  , then the state
1df80 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61  ment may be.** a
1df90 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
1dfa0 6f 6d 70 69 6c 65 64 20 28 61 73 20 69 66 20 74  ompiled (as if t
1dfb0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 61 20  here had been a 
1dfc0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 29 20 6f  schema change) o
1dfd0 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20  n the first .** 
1dfe0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1dff0 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
1e000 61 6e 79 20 63 68 61 6e 67 65 20 74 6f 20 74 68  any change to th
1e010 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  e .** [sqlite3_b
1e020 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
1e030 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b 70 61 72  ngs] of the [par
1e040 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c  ameter]. .** </l
1e050 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
1e060 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1e070 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
1e080 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1e090 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1e0a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1e0b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1e0c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1e0d0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1e0e0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1e0f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1e100 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1e110 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1e120 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1e130 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1e140 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1e150 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e160 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1e170 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1e180 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1e190 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1e1a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1e1b0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
1e1c0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1e1d0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1e1e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e1f0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1e200 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1e210 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1e220 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1e230 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1e240 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1e250 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1e260 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1e270 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1e280 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1e290 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1e2a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1e2b0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1e2c0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1e2d0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1e2e0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1e2f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
1e300 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1e310 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1e320 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1e330 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1e340 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1e350 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1e360 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1e370 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1e380 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1e390 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1e3a0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1e3b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1e3c0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1e3d0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1e3e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1e3f0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1e400 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1e410 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1e420 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1e430 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1e440 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
1e450 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1e460 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1e470 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e480 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1e490 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1e4a0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1e4b0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1e4c0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1e4d0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1e4e0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1e4f0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1e500 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1e510 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1e520 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1e530 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1e540 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1e550 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1e560 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1e570 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1e580 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
1e590 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
1e5a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
1e5b0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
1e5c0 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
1e5d0 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
1e5e0 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
1e5f0 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
1e600 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
1e610 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
1e620 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1e630 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
1e640 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1e650 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e660 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1e670 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1e680 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1e690 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1e6a0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1e6b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e6c0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1e6d0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1e6e0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1e6f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1e700 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
1e710 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1e720 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
1e730 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
1e740 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1e750 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
1e760 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
1e770 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
1e780 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1e790 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
1e7a0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
1e7b0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
1e7c0 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
1e7d0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
1e7e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e7f0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
1e800 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1e810 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1e820 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1e830 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1e840 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e850 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1e860 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1e870 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1e880 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1e890 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1e8a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e8b0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1e8c0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1e8d0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1e8e0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1e8f0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1e900 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1e910 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1e920 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1e930 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1e940 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
1e950 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
1e960 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
1e970 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e980 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
1e990 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
1e9a0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
1e9b0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
1e9c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
1e9d0 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
1e9e0 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
1e9f0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1ea00 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
1ea10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ea20 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
1ea30 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
1ea40 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1ea50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ea60 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
1ea70 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
1ea80 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
1ea90 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
1eaa0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
1eab0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
1eac0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
1ead0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
1eae0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
1eaf0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
1eb00 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
1eb10 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
1eb20 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1eb30 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1eb40 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
1eb50 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
1eb60 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1eb70 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
1eb80 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1eb90 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1eba0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1ebb0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
1ebc0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
1ebd0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
1ebe0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1ebf0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1ec00 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1ec10 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1ec20 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
1ec30 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1ec40 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
1ec50 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1ec60 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1ec70 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
1ec80 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
1ec90 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
1eca0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1ecb0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
1ecc0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
1ecd0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
1ece0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
1ecf0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
1ed00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1ed10 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
1ed20 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
1ed30 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1ed40 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
1ed50 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
1ed60 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
1ed70 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
1ed80 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
1ed90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1eda0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
1edb0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
1edc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
1edd0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
1ede0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
1edf0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
1ee00 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
1ee10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1ee20 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
1ee30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
1ee40 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
1ee50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1ee60 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
1ee70 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
1ee80 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
1ee90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1eea0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
1eeb0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
1eec0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
1eed0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
1eee0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
1eef0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
1ef00 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1ef10 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
1ef20 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
1ef30 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1ef40 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
1ef50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1ef60 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
1ef70 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1ef80 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
1ef90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1efa0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
1efb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
1efc0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
1efd0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
1efe0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
1eff0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
1f000 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
1f010 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
1f020 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
1f030 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
1f040 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
1f050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
1f060 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
1f070 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
1f080 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
1f090 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
1f0a0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
1f0b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1f0c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1f0d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
1f0e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f0f0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
1f100 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
1f110 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
1f120 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
1f130 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
1f140 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
1f150 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
1f160 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1f170 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
1f180 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
1f190 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
1f1a0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
1f1b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1f1c0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
1f1d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f1e0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1f1f0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
1f200 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
1f210 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
1f220 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
1f230 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
1f240 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
1f250 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1f260 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
1f270 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
1f280 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
1f290 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
1f2a0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
1f2b0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
1f2c0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
1f2d0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
1f2e0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
1f2f0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
1f300 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
1f310 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
1f320 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
1f330 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
1f340 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
1f350 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
1f360 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
1f370 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
1f380 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
1f390 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1f3a0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
1f3b0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
1f3c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1f3d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
1f3e0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1f3f0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
1f400 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1f410 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1f420 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
1f430 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
1f440 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1f450 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
1f460 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
1f470 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1f480 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
1f490 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
1f4a0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
1f4b0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
1f4c0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1f4d0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
1f4e0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
1f4f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
1f500 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
1f510 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
1f520 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
1f530 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
1f540 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
1f550 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
1f560 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
1f570 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
1f580 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
1f590 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
1f5a0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
1f5b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1f5c0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
1f5d0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
1f5e0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
1f5f0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
1f600 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
1f610 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
1f620 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
1f630 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
1f640 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1f650 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
1f660 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
1f670 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
1f680 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
1f690 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
1f6a0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
1f6b0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
1f6c0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
1f6d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
1f6e0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
1f6f0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
1f700 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
1f710 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
1f720 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1f730 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
1f740 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
1f750 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
1f760 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
1f770 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
1f780 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
1f790 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1f7a0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
1f7b0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1f7c0 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
1f7d0 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
1f7e0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
1f7f0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1f800 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
1f810 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1f820 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nator..**.** ^Th
1f830 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1f840 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
1f850 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
1f860 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
1f870 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
1f880 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
1f890 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
1f8a0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
1f8b0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
1f8c0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
1f8d0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1f8e0 74 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20 66  th it. ^If the f
1f8f0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
1f900 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
1f910 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
1f920 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
1f930 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
1f940 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
1f950 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
1f960 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
1f970 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
1f980 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
1f990 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
1f9a0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
1f9b0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
1f9c0 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
1f9d0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
1f9e0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
1f9f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
1fa00 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
1fa10 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
1fa20 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1fa30 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
1fa40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1fa50 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
1fa60 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
1fa70 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
1fa80 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
1fa90 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
1faa0 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
1fab0 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
1fac0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
1fad0 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
1fae0 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
1faf0 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
1fb00 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
1fb10 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
1fb20 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
1fb30 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
1fb40 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
1fb50 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
1fb60 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
1fb70 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1fb80 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
1fb90 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
1fba0 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
1fbb0 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
1fbc0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
1fbd0 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
1fbe0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
1fbf0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
1fc00 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
1fc10 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1fc20 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
1fc30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1fc40 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
1fc50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1fc60 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
1fc70 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
1fc80 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
1fc90 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
1fca0 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
1fcb0 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
1fcc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
1fcd0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
1fce0 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
1fcf0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
1fd00 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
1fd10 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
1fd20 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
1fd30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fd40 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
1fd50 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
1fd60 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
1fd70 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
1fd80 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1fd90 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
1fda0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
1fdb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
1fdc0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
1fdd0 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
1fde0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
1fdf0 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
1fe00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1fe10 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
1fe20 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
1fe30 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
1fe40 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
1fe50 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
1fe60 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
1fe70 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
1fe80 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1fe90 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
1fea0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
1feb0 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
1fec0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
1fed0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
1fee0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
1fef0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1ff00 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1ff10 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
1ff20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1ff30 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
1ff40 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1ff50 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1ff60 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1ff70 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
1ff80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1ff90 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1ffa0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
1ffb0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1ffc0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
1ffd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1ffe0 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
1fff0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
20000 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20010 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
20020 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
20030 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20040 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
20050 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
20060 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
20070 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
20080 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20090 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
200a0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
200b0 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
200c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
200d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
200e0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
200f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
20100 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
20110 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
20120 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
20130 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
20140 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
20150 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
20160 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20170 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
20180 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
20190 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
201a0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
201b0 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
201c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
201d0 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
201e0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
201f0 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
20200 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
20210 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20220 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
20230 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
20240 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
20250 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
20260 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
20270 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
20280 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
20290 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
202a0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
202b0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
202c0 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
202d0 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
202e0 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
202f0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
20300 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
20310 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
20320 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
20330 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
20340 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
20350 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
20360 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
20370 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
20380 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
20390 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
203a0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
203b0 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
203c0 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
203d0 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
203e0 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
203f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
20400 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
20410 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
20420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
20430 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
20440 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
20450 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
20460 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
20470 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
20480 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
20490 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
204a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
204b0 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
204c0 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68  ameter.**.** ^Th
204d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
204e0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
204f0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
20500 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
20510 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
20520 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
20530 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
20540 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
20550 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
20560 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
20570 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
20580 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
20590 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
205a0 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
205b0 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
205c0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
205d0 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
205e0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
205f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
20600 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
20610 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
20620 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
20630 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
20640 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
20650 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
20660 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
20670 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
20680 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
20690 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
206a0 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
206b0 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
206c0 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
206d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
206e0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
206f0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
20700 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
20710 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
20720 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
20730 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
20740 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
20750 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
20760 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
20770 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
20780 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
20790 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
207a0 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
207b0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
207c0 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
207d0 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
207e0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
207f0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
20800 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
20810 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
20820 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
20830 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
20840 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
20850 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
20860 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
20870 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
20880 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20890 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
208a0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
208b0 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
208c0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
208d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
208e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
208f0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
20900 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
20910 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20  iven Name.**.** 
20920 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
20930 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
20940 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
20950 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
20960 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
20970 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
20980 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
20990 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
209a0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
209b0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
209c0 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
209d0 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
209e0 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
209f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
20a00 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
20a10 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
20a20 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
20a30 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
20a40 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
20a50 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
20a60 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
20a70 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
20a80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
20a90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
20aa0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
20ab0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
20ac0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
20ad0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20ae0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
20af0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
20b00 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
20b10 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
20b20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
20b30 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
20b40 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
20b50 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
20b60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
20b70 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
20b80 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
20b90 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
20ba0 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
20bb0 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
20bc0 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
20bd0 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
20be0 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
20bf0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
20c00 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
20c10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20c20 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
20c30 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
20c40 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
20c50 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
20c60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
20c70 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
20c80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
20c90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
20ca0 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
20cb0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
20cc0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
20cd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
20ce0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
20cf0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
20d00 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
20d10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
20d20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
20d30 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
20d40 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
20d50 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
20d60 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
20d70 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
20d80 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a  n [UPDATE])..*/.
20d90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
20da0 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
20db0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
20dc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20dd0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
20de0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
20df0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
20e00 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
20e10 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
20e20 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
20e30 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
20e40 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
20e50 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
20e60 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
20e70 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
20e80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
20e90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
20ea0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
20eb0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
20ec0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
20ed0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
20ee0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
20ef0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
20f00 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
20f10 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
20f20 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
20f30 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
20f40 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
20f50 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
20f60 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
20f70 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
20f80 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
20f90 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
20fa0 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
20fb0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
20fc0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
20fd0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
20fe0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
20ff0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
21000 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
21010 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
21020 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
21030 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
21040 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
21050 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
21060 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
21070 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
21080 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
21090 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
210a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
210b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
210c0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
210d0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
210e0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
210f0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
21100 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
21110 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
21120 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
21130 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
21140 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
21150 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
21160 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
21170 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
21180 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
21190 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
211a0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
211b0 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
211c0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
211d0 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
211e0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
211f0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
21200 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
21210 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
21220 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
21230 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
21240 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
21250 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
21260 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21270 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
21280 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
21290 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
212a0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
212b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
212c0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
212d0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
212e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
212f0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
21300 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
21310 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
21320 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
21330 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
21340 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
21350 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
21360 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
21370 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
21380 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
21390 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
213a0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
213b0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
213c0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
213d0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
213e0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
213f0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
21400 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
21410 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
21420 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
21430 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
21440 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
21450 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
21460 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
21470 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
21480 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
21490 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
214a0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
214b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
214c0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
214d0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
214e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
214f0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
21500 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
21510 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
21520 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
21530 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
21540 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
21550 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
21560 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
21570 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
21580 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
21590 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
215a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
215b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
215c0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
215d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
215e0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
215f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
21600 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
21610 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
21620 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
21630 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
21640 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
21650 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
21660 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
21670 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
21680 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
21690 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
216a0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
216b0 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
216c0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
216d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
216e0 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
216f0 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
21700 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
21710 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
21720 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
21730 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
21740 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
21750 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
21760 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
21770 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
21780 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
21790 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
217a0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
217b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
217c0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
217d0 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
217e0 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
217f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
21800 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
21810 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
21820 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
21830 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
21840 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
21850 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
21860 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
21870 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
21880 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
21890 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
218a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
218b0 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
218c0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
218d0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
218e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
218f0 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
21900 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
21910 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
21920 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
21930 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
21940 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
21950 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
21960 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
21970 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
21980 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
21990 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
219a0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
219b0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
219c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
219d0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
219e0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
219f0 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
21a00 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
21a10 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
21a20 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
21a30 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
21a40 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
21a50 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
21a60 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
21a70 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
21a80 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
21a90 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
21aa0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
21ab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
21ac0 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
21ad0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
21ae0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
21af0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
21b00 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
21b10 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
21b20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
21b30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
21b40 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
21b50 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
21b60 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
21b70 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
21b80 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
21b90 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
21ba0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21bb0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
21bc0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
21bd0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
21be0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
21bf0 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
21c00 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
21c10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
21c20 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
21c30 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
21c40 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
21c50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
21c60 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
21c70 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
21c80 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
21c90 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
21ca0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
21cb0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
21cc0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
21cd0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
21ce0 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
21cf0 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
21d00 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
21d10 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
21d20 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
21d30 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
21d40 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
21d50 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
21d60 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
21d70 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
21d80 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
21d90 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
21da0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
21db0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
21dc0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
21dd0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
21de0 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
21df0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
21e00 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
21e10 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
21e20 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
21e30 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
21e40 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
21e50 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
21e60 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
21e70 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
21e80 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
21e90 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
21ea0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
21eb0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
21ec0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
21ed0 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
21ee0 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
21ef0 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
21f00 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
21f10 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
21f20 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
21f30 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
21f40 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
21f50 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
21f60 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
21f70 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
21f80 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
21f90 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
21fa0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
21fb0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
21fc0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
21fd0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
21fe0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
21ff0 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
22000 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
22010 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
22020 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
22030 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
22040 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
22050 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
22060 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
22070 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
22080 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
22090 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
220a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
220b0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
220c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
220d0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
220e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
220f0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
22100 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
22110 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22120 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
22130 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
22140 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
22150 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
22160 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
22170 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
22180 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22190 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
221a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
221b0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
221c0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
221d0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
221e0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
221f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
22200 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
22210 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
22220 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
22230 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
22240 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
22250 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
22260 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
22270 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
22280 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
22290 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
222a0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
222b0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
222c0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
222d0 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
222e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
222f0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
22300 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22310 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
22320 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
22330 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
22340 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
22350 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
22360 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
22370 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
22380 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
22390 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
223a0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
223b0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
223c0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
223d0 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
223e0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
223f0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
22400 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
22410 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
22420 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
22430 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
22440 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
22450 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
22460 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
22470 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
22480 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
22490 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
224a0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
224b0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
224c0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
224d0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
224e0 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
224f0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
22500 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
22510 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
22520 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
22530 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
22540 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
22550 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
22560 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
22570 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
22580 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
22590 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
225a0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
225b0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
225c0 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
225d0 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
225e0 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
225f0 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
22600 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
22610 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a  curs within a.**
22620 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
22630 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
22640 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
22650 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
22660 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
22670 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
22680 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
22690 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
226a0 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
226b0 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
226c0 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
226d0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
226e0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
226f0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
22700 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
22710 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
22720 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
22730 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
22740 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
22750 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
22760 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
22770 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
22780 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
22790 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
227a0 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
227b0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
227c0 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
227d0 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
227e0 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
227f0 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
22800 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
22810 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
22820 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
22830 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
22840 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
22850 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
22860 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
22870 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
22880 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
22890 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
228a0 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
228b0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
228c0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
228d0 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
228e0 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
228f0 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
22900 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
22910 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
22920 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
22930 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
22940 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
22950 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
22960 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
22970 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
22980 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
22990 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
229a0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
229b0 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
229c0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
229d0 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
229e0 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
229f0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
22a00 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
22a10 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
22a20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
22a30 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
22a40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22a50 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
22a60 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
22a70 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
22a80 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
22a90 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
22aa0 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
22ab0 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
22ac0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
22ad0 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
22ae0 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
22af0 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
22b00 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
22b10 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
22b20 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
22b30 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
22b40 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
22b50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22b60 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
22b70 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
22b80 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
22b90 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
22ba0 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
22bb0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
22bc0 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
22bd0 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
22be0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
22bf0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
22c00 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
22c10 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
22c20 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
22c30 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
22c40 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
22c50 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
22c60 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
22c70 67 20 33 2e 36 2e 32 33 2e 31 2c 20 69 74 20 77  g 3.6.23.1, it w
22c80 61 73 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 61  as required.** a
22c90 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
22ca0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
22cb0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
22cc0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 74 68   [SQLITE_ROW] th
22cd0 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  at.** [sqlite3_r
22ce0 65 73 65 74 28 29 5d 20 62 65 20 63 61 6c 6c 65  eset()] be calle
22cf0 64 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  d before any sub
22d00 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
22d10 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
22d20 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
22d30 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  e to invoke [sql
22d40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
22d50 20 74 68 69 73 20 77 61 79 20 77 6f 75 6c 64 0a   this way would.
22d60 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ** result in an 
22d70 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
22d80 72 65 74 75 72 6e 20 66 72 6f 6d 20 73 71 6c 69  return from sqli
22d90 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
22da0 20 61 66 74 65 72 0a 2a 2a 20 76 65 72 73 69 6f   after.** versio
22db0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
22dc0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
22dd0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
22de0 33 5f 72 65 73 65 74 28 29 5d 20 0a 2a 2a 20 61  3_reset()] .** a
22df0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
22e00 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
22e10 65 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65  e rather than re
22e20 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
22e30 4d 49 53 55 53 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a  MISUSE].  .**.**
22e40 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
22e50 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
22e60 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
22e70 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
22e80 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
22e90 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
22ea0 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
22eb0 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
22ec0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
22ed0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
22ee0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
22ef0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
22f00 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
22f10 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
22f20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22f30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
22f40 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
22f50 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
22f60 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
22f70 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
22f80 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
22f90 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
22fa0 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
22fb0 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
22fc0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
22fd0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
22fe0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
22ff0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
23000 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
23010 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
23020 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
23030 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
23040 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23050 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
23060 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
23070 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
23080 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
23090 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
230a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
230b0 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
230c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
230d0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
230e0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
230f0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
23100 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
23110 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
23120 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
23130 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
23140 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
23150 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
23160 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
23170 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
23180 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
23190 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
231a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
231b0 74 61 5f 63 6f 75 6e 74 28 50 29 20 74 68 65 20  ta_count(P) the 
231c0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
231d0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6f 66 20 74  s in the.** of t
231e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
231f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23200 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69 6e 74 20  ment] P..*/.int 
23210 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
23220 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
23230 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
23240 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
23250 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
23260 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
23270 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
23280 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
23290 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
232a0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
232b0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
232c0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
232d0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
232e0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
232f0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
23300 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
23310 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
23320 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
23330 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
23340 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
23350 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
23360 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
23370 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
23380 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
23390 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
233a0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
233b0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
233c0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
233d0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
233e0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
233f0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
23400 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
23410 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
23420 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
23430 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
23440 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
23450 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
23460 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
23470 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
23480 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
23490 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
234a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
234b0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
234c0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
234d0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
234e0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
234f0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
23500 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
23510 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
23520 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
23530 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
23540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
23550 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
23560 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
23570 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
23580 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
23590 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
235a0 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
235b0 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
235c0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
235d0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
235e0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
235f0 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
23600 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
23610 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
23620 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
23630 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
23640 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
23650 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
23660 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
23670 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
23680 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
23690 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
236a0 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
236b0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
236c0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
236d0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
236e0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
236f0 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
23700 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
23710 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
23720 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
23730 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
23740 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
23750 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
23760 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
23770 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
23780 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
23790 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
237a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
237b0 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
237c0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
237d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
237e0 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
237f0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
23800 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
23810 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
23820 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
23830 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
23840 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
23850 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
23860 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
23870 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
23880 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
23890 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
238a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
238b0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
238c0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
238d0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
238e0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
238f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
23900 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
23910 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
23920 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
23930 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
23940 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
23950 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
23960 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
23970 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
23980 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23990 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
239a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
239b0 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
239c0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
239d0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
239e0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
239f0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
23a00 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
23a10 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
23a20 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
23a30 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
23a40 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
23a50 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
23a60 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
23a70 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
23a80 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
23a90 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
23aa0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
23ab0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
23ac0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
23ad0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
23ae0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
23af0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
23b00 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
23b10 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
23b20 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
23b30 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
23b40 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
23b50 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
23b60 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
23b70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
23b80 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
23b90 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
23ba0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
23bb0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
23bc0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
23bd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
23be0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
23bf0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
23c00 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
23c10 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
23c20 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
23c30 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
23c40 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
23c50 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
23c60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
23c70 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
23c80 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
23c90 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
23ca0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
23cb0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
23cc0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
23cd0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
23ce0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
23cf0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
23d00 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
23d10 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
23d20 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
23d30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23d40 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
23d50 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
23d60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
23d70 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
23d80 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
23d90 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
23da0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
23db0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
23dc0 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
23dd0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
23de0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
23df0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
23e00 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
23e10 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
23e20 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
23e30 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
23e40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
23e50 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
23e60 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
23e70 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
23e80 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
23e90 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
23ea0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
23eb0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
23ec0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54 68 65 20  string..** ^The 
23ed0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64  value returned d
23ee0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
23ef0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
23f00 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  tor at the end.*
23f10 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
23f20 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
23f30 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
23f40 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ed is the number
23f50 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
23f60 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
23f70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
23f80 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
23f90 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
23fa0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
23fb0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
23fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23fd0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
23fe0 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
23ff0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
24000 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
24010 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
24020 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
24030 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
24040 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
24050 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  OB is an arbitra
24060 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70  ry.** pointer, p
24070 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e  ossibly even a N
24080 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
24090 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
240a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
240b0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
240c0 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lar to sqlite3_c
240d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
240e0 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20   but leaves the 
240f0 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36  result in UTF-16
24100 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
24110 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
24120 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54 68 65 20   UTF-8..** ^The 
24130 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
24140 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
24150 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
24160 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
24170 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
24180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
24190 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
241a0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
241b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
241c0 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
241d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
241e0 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
241f0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
24200 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
24210 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
24220 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
24230 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
24240 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
24250 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
24260 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
24270 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
24280 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
24290 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
242a0 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
242b0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
242c0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
242d0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
242e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
242f0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
24300 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
24310 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
24320 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
24330 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
24340 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
24350 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
24360 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
24370 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
24380 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
24390 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
243a0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
243b0 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
243c0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
243d0 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
243e0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
243f0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
24400 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
24410 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
24420 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
24430 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
24440 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
24450 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
24460 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
24470 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
24480 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
24490 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
244a0 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
244b0 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
244c0 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
244d0 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
244e0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
244f0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
24500 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
24510 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
24520 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
24530 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
24540 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
24550 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
24560 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
24570 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
24580 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
24590 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
245a0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
245b0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
245c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
245d0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
245e0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
245f0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
24600 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
24610 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
24620 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
24630 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
24640 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
24650 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
24660 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
24670 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
24680 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
24690 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
246a0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
246b0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
246c0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
246d0 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
246e0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
246f0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
24700 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
24710 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
24720 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
24730 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
24740 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
24750 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
24760 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
24770 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
24780 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
24790 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
247a0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
247b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
247c0 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
247d0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
247e0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
247f0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
24800 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
24810 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
24820 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
24830 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
24840 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
24850 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
24860 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
24870 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
24880 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
24890 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
248a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
248b0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
248c0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
248d0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
248e0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
248f0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
24900 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
24910 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
24920 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
24930 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
24940 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
24950 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
24960 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
24970 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
24980 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
24990 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
249a0 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
249b0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
249c0 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
249d0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
249e0 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
249f0 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
24a00 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
24a10 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
24a20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
24a30 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
24a40 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
24a50 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
24a60 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
24a70 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
24a80 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
24a90 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
24aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
24ab0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
24ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24ad0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
24ae0 69 64 61 74 65 64 2e 0a 2a 2a 20 5e 28 54 79 70  idated..** ^(Typ
24af0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
24b00 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
24b10 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
24b20 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
24b30 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
24b40 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
24b50 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
24b60 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
24b70 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
24b80 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
24b90 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
24ba0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
24bb0 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
24bc0 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
24bd0 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
24be0 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
24bf0 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
24c00 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
24c10 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
24c20 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
24c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24c40 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
24c50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24c60 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
24c70 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
24c80 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
24c90 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
24ca0 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
24cb0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
24cc0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
24cd0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
24ce0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
24cf0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
24d00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
24d10 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
24d20 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
24d30 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
24d40 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
24d50 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  >.** </ul>)^.**.
24d60 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
24d70 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
24d80 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
24d90 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
24da0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
24db0 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
24dc0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
24dd0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
24de0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
24df0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
24e00 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
24e10 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20  inter points to 
24e20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
24e30 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
24e40 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
24e50 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
24e60 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
24e70 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
24e80 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
24e90 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
24ea0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
24eb0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
24ec0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
24ed0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  idated..**.** ^(
24ee0 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
24ef0 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
24f00 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
24f10 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
24f20 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
24f30 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
24f40 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
24f50 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
24f60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
24f70 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
24f80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24f90 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
24fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24fb0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
24fc0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
24fd0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
24fe0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
24ff0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
25000 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
25010 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
25020 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
25030 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  )^.**.** In othe
25040 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
25050 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
25060 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
25070 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
25080 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
25090 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
250a0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
250b0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
250c0 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
250d0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
250e0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
250f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
25100 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
25110 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
25120 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
25130 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
25140 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
25150 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
25160 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
25170 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
25180 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
25190 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
251a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
251b0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
251c0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
251d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
251e0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
251f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25200 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
25210 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
25220 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
25230 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
25240 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
25250 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
25260 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
25270 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
25280 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
25290 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
252a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
252b0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
252c0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
252d0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
252e0 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
252f0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
25300 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
25310 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
25320 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
25330 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
25340 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
25350 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
25360 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
25370 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
25380 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
25390 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
253a0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
253b0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
253c0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
253d0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
253e0 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
253f0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
25400 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
25410 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
25420 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
25430 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
25440 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
25450 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
25460 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
25470 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
25480 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
25490 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
254a0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
254b0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
254c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
254d0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
254e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
254f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25500 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
25510 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
25520 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
25530 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
25540 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
25550 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
25560 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
25570 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25580 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
25590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
255a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
255b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
255c0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
255d0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
255e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
255f0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
25600 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
25610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
25620 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
25630 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
25640 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
25650 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
25660 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25670 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
25680 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
25690 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
256a0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
256b0 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
256c0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
256d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
256e0 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
256f0 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
25700 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
25710 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
25720 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25730 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
25740 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
25750 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
25760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
25770 2a 2a 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  ** ^If the state
25780 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65  ment was execute
25790 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  d successfully o
257a0 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61  r not executed a
257b0 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53  t all, then.** S
257c0 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
257d0 72 6e 65 64 2e 20 5e 49 66 20 65 78 65 63 75 74  rned. ^If execut
257e0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
257f0 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
25800 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
25810 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
25820 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
25830 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
25840 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
25850 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
25860 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20  ny point during 
25870 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
25880 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
25890 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
258a0 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d  If the virtual m
258b0 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a  achine has not.*
258c0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
258d0 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
258e0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
258f0 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
25900 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
25910 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b  an error or an [
25920 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
25930 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a  t | interrupt]..
25940 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74 65 20 75  ** ^Incomplete u
25950 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f  pdates may be ro
25960 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72  lled back and tr
25970 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65  ansactions cance
25980 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  led,.** dependin
25990 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73  g on the circums
259a0 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a  tances, and the.
259b0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
259c0 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65  returned will be
259d0 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
259e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
259f0 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
25a00 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
25a10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25a20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
25a30 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
25a40 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
25a50 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
25a60 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
25a70 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
25a80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
25a90 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
25aa0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
25ab0 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
25ac0 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
25ad0 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
25ae0 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
25af0 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
25b00 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
25b10 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
25b20 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
25b30 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
25b40 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
25b50 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
25b60 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
25b70 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
25b80 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
25b90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
25ba0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
25bb0 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
25bc0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25bd0 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
25be0 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
25bf0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
25c00 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
25c10 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
25c20 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
25c30 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
25c40 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
25c50 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
25c60 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
25c70 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
25c80 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
25c90 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
25ca0 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
25cb0 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
25cc0 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
25cd0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
25ce0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
25cf0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
25d00 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
25d10 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
25d20 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
25d30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25d40 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
25d50 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
25d60 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
25d70 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
25d80 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
25d90 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
25da0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
25db0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
25dc0 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
25dd0 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
25de0 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
25df0 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
25e00 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
25e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25e20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
25e30 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
25e40 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
25e50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
25e60 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
25e70 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
25e80 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
25e90 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
25ea0 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
25eb0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
25ec0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
25ed0 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
25ee0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
25ef0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
25f00 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
25f10 20 5e 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63   ^These two func
25f20 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
25f30 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
25f40 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
25f50 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
25f60 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
25f70 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
25f80 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
25f90 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
25fa0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
25fb0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
25fc0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
25fd0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
25fe0 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74  erence between t
25ff0 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61  he.** two is tha
26000 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  t the second par
26010 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65  ameter, the name
26020 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29   of the (scalar)
26030 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
26040 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e  aggregate, is en
26050 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66  coded in UTF-8 f
26060 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
26070 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
26080 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73   UTF-16.** for s
26090 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
260a0 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  nction16()..**.*
260b0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
260c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
260d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
260e0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
260f0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
26100 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
26110 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
26120 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
26130 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
26140 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
26150 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
26160 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
26170 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
26180 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
26190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
261a0 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
261b0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
261c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
261d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
261e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
261f0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
26200 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
26210 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
26220 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
26230 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75  255 bytes, exclu
26240 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a  sive of.** the z
26250 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
26260 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e   Note that the n
26270 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  ame length limit
26280 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f   is in bytes, no
26290 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e  t.** characters.
262a0 20 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74    ^Any attempt t
262b0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
262c0 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
262d0 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
262e0 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
262f0 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65  _ERROR] being re
26300 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
26310 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
26320 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
26330 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
26340 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
26350 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
26360 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
26370 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
26380 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
26390 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
263a0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
263b0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
263c0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
263d0 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
263e0 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
263f0 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
26400 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
26410 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
26420 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
26430 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
26440 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
26450 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
26460 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
26470 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
26480 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
26490 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
264a0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
264b0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
264c0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
264d0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
264e0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
264f0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
26500 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
26510 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
26520 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26530 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
26540 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
26550 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
26560 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
26570 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
26580 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
26590 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
265a0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
265b0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
265c0 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63  her.  ^An applic
265d0 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
265e0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
265f0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
26600 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
26610 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
26620 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
26630 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
26640 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
26650 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
26660 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
26670 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
26680 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
26690 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
266a0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
266b0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
266c0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
266d0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
266e0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
266f0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
26700 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
26710 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
26720 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
26730 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
26740 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
26750 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
26760 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
26770 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
26780 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
26790 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
267a0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
267b0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
267c0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
267d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
267e0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
267f0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
26800 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
26810 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
26820 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
26830 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20  ** The seventh, 
26840 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68  eighth and ninth
26850 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
26860 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
26870 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
26880 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
26890 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
268a0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
268b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
268c0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
268d0 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
268e0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
268f0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
26900 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
26910 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
26920 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68  NULL pointers sh
26930 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61  ould be passed a
26940 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
26950 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
26960 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
26970 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
26980 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
26990 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
269a0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
269b0 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75  al and NULL shou
269c0 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  ld be passed for
269d0 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
269e0 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
269f0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
26a00 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
26a10 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74  s NULL for all t
26a20 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61  hree function ca
26a30 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
26a40 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
26a50 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
26a60 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
26a70 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
26a80 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
26a90 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
26aa0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
26ab0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
26ac0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
26ad0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
26ae0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
26af0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
26b00 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
26b10 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
26b20 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
26b30 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
26b40 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
26b50 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
26b60 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
26b70 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
26b80 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
26b90 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
26ba0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
26bb0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
26bc0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
26bd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
26be0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
26bf0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
26c00 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
26c10 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
26c20 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
26c30 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
26c40 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
26c50 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
26c60 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
26c70 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
26c80 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
26c90 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
26ca0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
26cb0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
26cc0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
26cd0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
26ce0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
26cf0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
26d00 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
26d10 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
26d20 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
26d30 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
26d40 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
26d50 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
26d60 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
26d70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26d80 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20  d functions..** 
26d90 5e 54 68 65 20 66 69 72 73 74 20 61 70 70 6c 69  ^The first appli
26da0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
26db0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 67  unction with a g
26dc0 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69  iven name overri
26dd0 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74  des all.** built
26de0 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e  -in functions in
26df0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
26e00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26e10 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
26e20 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73 65 71 75 65  me..** ^Subseque
26e30 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  nt application-d
26e40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
26e50 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   of the same nam
26e60 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20  e only override 
26e70 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63  .** prior applic
26e80 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26e90 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  nctions that are
26ea0 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20   an exact match 
26eb0 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  for the.** numbe
26ec0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
26ed0 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e  and preferred en
26ee0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 41  coding..**.** ^A
26ef0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
26f00 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
26f10 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
26f20 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
26f30 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
26f40 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
26f50 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
26f60 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
26f70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
26f80 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
26f90 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
26fa0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
26fb0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
26fc0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
26fd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
26fe0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
26ff0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
27000 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
27010 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
27020 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
27030 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
27040 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
27050 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
27060 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
27070 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
27080 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
27090 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
270a0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
270b0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
270c0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
270d0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
270e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
270f0 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
27100 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
27110 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
27120 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
27130 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
27140 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
27150 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
27160 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27170 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
27180 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
27190 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
271a0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
271b0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
271c0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
271d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
271e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
271f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
27200 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
27210 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
27220 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
27230 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
27240 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
27250 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
27260 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
27270 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
27280 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
27290 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
272a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
272b0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
272c0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
272d0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
272e0 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
272f0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
27300 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
27310 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
27320 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
27330 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
27340 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
27350 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
27360 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
27370 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
27380 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
27390 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
273a0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
273b0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
273c0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
273d0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
273e0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
273f0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
27400 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
27410 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
27420 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
27430 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
27440 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
27450 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
27460 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27470 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
27480 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
27490 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
274a0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
274b0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
274c0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
274d0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
274e0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
274f0 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
27500 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
27510 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
27520 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
27530 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
27540 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
27550 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
27560 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
27570 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
27580 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
27590 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
275a0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
275b0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
275c0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
275d0 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
275e0 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
275f0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
27600 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
27610 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
27620 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
27630 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
27640 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
27650 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
27660 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
27670 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
27680 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
27690 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
276a0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
276b0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
276c0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
276d0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
276e0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
276f0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
27700 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
27710 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
27720 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
27730 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
27740 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
27750 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
27760 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
27770 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
27780 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
27790 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
277a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
277b0 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
277c0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
277d0 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
277e0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
277f0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
27800 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
27810 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
27820 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
27830 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
27840 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
27850 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
27860 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
27870 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
27880 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
27890 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
278a0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
278b0 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
278c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
278d0 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
278e0 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
278f0 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
27900 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
27910 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
27920 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
27930 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27940 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
27950 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27960 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
27970 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
27980 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
27990 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
279a0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
279b0 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
279c0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
279d0 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
279e0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
279f0 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
27a00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
27a10 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
27a20 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
27a30 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
27a40 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
27a50 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
27a60 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
27a70 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
27a80 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
27a90 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
27aa0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
27ab0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
27ac0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
27ad0 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
27ae0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27af0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
27b00 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
27b10 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
27b20 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
27b30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27b40 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
27b50 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
27b60 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
27b70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
27b80 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
27b90 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
27ba0 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
27bb0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
27bc0 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
27bd0 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
27be0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
27bf0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
27c00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
27c10 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
27c20 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
27c30 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
27c40 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
27c50 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
27c60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27c70 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
27c80 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
27c90 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
27ca0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
27cb0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
27cc0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
27cd0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
27ce0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27cf0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
27d00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
27d10 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
27d20 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
27d30 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
27d40 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
27d50 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
27d60 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
27d70 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
27d80 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
27d90 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
27da0 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
27db0 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
27dc0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
27dd0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
27de0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
27df0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
27e00 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
27e10 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
27e20 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
27e30 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
27e40 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
27e50 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
27e60 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
27e70 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
27e80 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
27e90 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
27ea0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
27eb0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
27ec0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
27ed0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
27ee0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
27ef0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
27f00 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
27f10 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
27f20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
27f30 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
27f40 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
27f50 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
27f60 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
27f70 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
27f80 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
27f90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
27fa0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
27fb0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
27fc0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
27fd0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
27fe0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
27ff0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
28000 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
28010 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
28020 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
28030 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
28040 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
28050 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
28060 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28070 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
28080 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
28090 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
280a0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
280b0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
280c0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
280d0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
280e0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
280f0 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  eters..*/.const 
28100 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
28110 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
28120 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
28130 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
28140 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
28150 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
28160 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
28170 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
28180 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
28190 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
281a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
281b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
281c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
281d0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
281e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
281f0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
28200 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
28210 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
28220 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
28230 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
28240 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
28250 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
28260 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28270 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28280 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
28290 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
282a0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
282b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
282c0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
282d0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
282e0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
282f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28300 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
28310 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
28320 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28330 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28340 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
28350 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
28360 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
28370 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
28380 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
28390 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
283a0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
283b0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
283c0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
283d0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
283e0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
283f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
28400 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
28410 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
28420 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
28430 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
28440 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
28450 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
28460 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
28470 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
28480 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
28490 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
284a0 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
284b0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
284c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
284d0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
284e0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
284f0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
28500 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
28510 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
28520 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
28530 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
28540 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
28550 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
28560 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
28570 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
28580 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
28590 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
285a0 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
285b0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
285c0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
285d0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
285e0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
285f0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
28600 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
28610 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
28620 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
28630 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
28640 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
28650 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
28660 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
28670 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
28680 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
28690 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
286a0 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
286b0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
286c0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
286d0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
286e0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
286f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
28700 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
28710 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
28720 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
28730 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
28740 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
28750 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
28760 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
28770 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
28780 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
28790 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
287a0 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
287b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
287c0 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
287d0 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
287e0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
287f0 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
28800 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
28810 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
28820 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
28830 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
28840 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
28850 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
28860 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
28870 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
28880 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
28890 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
288a0 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
288b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
288c0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
288d0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
288e0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
288f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
28900 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
28910 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
28920 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
28930 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
28940 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
28950 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
28960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
28970 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
28980 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
28990 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
289a0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
289b0 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
289c0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
289d0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
289e0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
289f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
28a00 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
28a10 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
28a20 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
28a30 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
28a40 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
28a50 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
28a60 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
28a70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28a80 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
28a90 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
28aa0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
28ab0 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
28ac0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
28ad0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28ae0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
28af0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28b00 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
28b10 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
28b20 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
28b30 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
28b40 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
28b50 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
28b60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28b70 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
28b80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
28b90 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
28ba0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
28bb0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
28bc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
28bd0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
28be0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
28bf0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
28c00 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
28c10 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
28c20 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
28c30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
28c40 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
28c50 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
28c60 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
28c70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
28c80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28c90 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
28ca0 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
28cb0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
28cc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
28cd0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
28ce0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
28cf0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
28d00 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
28d10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28d20 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
28d30 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
28d40 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
28d50 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
28d60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
28d70 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
28d80 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
28d90 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
28da0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
28db0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
28dc0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  function..*/.sql
28dd0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
28de0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
28df0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28e00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28e10 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
28e20 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
28e30 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
28e40 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
28e50 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
28e60 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
28e70 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
28e80 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
28e90 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
28ea0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
28eb0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
28ec0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
28ed0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
28ee0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
28ef0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
28f00 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
28f10 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
28f20 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
28f30 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
28f40 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
28f50 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
28f60 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
28f70 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
28f80 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
28f90 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
28fa0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
28fb0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
28fc0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
28fd0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
28fe0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
28ff0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
29000 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
29010 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
29020 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
29030 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
29040 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
29050 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
29060 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
29070 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
29080 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
29090 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
290a0 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
290b0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
290c0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
290d0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
290e0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
290f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
29100 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
29110 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
29120 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
29130 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
29140 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
29150 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
29160 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
29170 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
29180 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
29190 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
291a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
291b0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
291c0 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
291d0 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
291e0 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
291f0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
29200 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
29210 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
29220 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
29230 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
29240 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
29250 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
29260 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
29270 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
29280 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
29290 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
292a0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
292b0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
292c0 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
292d0 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
292e0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
292f0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
29300 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
29310 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
29320 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
29330 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29340 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
29350 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
29360 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
29370 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
29380 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
29390 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
293a0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
293b0 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
293c0 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
293d0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
293e0 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
293f0 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
29400 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
29410 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
29420 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
29430 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
29440 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
29450 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
29460 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
29470 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
29480 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
29490 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
294a0 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
294b0 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
294c0 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
294d0 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
294e0 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
294f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
29500 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
29510 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
29520 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
29530 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
29540 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
29550 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
29560 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
29570 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
29580 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
29590 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
295a0 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
295b0 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
295c0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
295d0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
295e0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
295f0 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
29600 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
29610 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
29620 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
29630 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
29640 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
29650 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
29660 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
29670 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
29680 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
29690 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
296a0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
296b0 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
296c0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
296d0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
296e0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
296f0 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
29700 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
29710 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
29720 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
29730 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
29740 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
29750 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
29760 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
29770 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
29780 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
29790 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
297a0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
297b0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
297c0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
297d0 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
297e0 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
297f0 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
29800 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
29810 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
29820 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
29830 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
29840 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
29850 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
29860 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
29870 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
29880 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
29890 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
298a0 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
298b0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
298c0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
298d0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
298e0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
298f0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
29900 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
29910 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
29920 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
29930 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
29940 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
29950 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
29960 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
29970 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
29980 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
29990 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
299a0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
299b0 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
299c0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
299d0 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
299e0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
299f0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
29a00 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
29a10 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
29a20 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
29a30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
29a40 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
29a50 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
29a60 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
29a70 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
29a80 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
29a90 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
29aa0 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
29ab0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
29ac0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
29ad0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
29ae0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29af0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
29b00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29b10 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
29b20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
29b30 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
29b40 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
29b50 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
29b60 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
29b70 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
29b80 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
29b90 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
29ba0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
29bb0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
29bc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
29bd0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
29be0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
29bf0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
29c00 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
29c10 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
29c20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29c30 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
29c40 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
29c50 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
29c60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29c70 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
29c80 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
29c90 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
29ca0 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
29cb0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
29cc0 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
29cd0 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
29ce0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
29cf0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
29d00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29d10 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
29d20 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
29d30 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
29d40 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
29d50 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29d60 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
29d70 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
29d80 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
29d90 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
29da0 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
29db0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
29dc0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
29dd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29de0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
29df0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
29e00 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
29e10 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
29e20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29e30 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
29e40 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
29e50 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
29e60 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
29e70 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
29e80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29e90 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
29ea0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
29eb0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
29ec0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
29ed0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
29ee0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
29ef0 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
29f00 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
29f10 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
29f20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
29f30 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
29f40 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
29f50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
29f60 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
29f70 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
29f80 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
29f90 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
29fa0 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
29fb0 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
29fc0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
29fd0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
29fe0 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
29ff0 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
2a000 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2a010 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a020 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
2a030 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
2a040 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
2a050 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2a060 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
2a070 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
2a080 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2a090 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
2a0a0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
2a0b0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
2a0c0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2a0d0 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
2a0e0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2a0f0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
2a100 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
2a110 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2a120 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a130 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
2a140 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2a150 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
2a160 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
2a170 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
2a180 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
2a190 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
2a1a0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2a1b0 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
2a1c0 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
2a1d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2a1e0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2a1f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2a200 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
2a210 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
2a220 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
2a230 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
2a240 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
2a250 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
2a260 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2a270 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
2a280 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
2a290 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
2a2a0 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
2a2b0 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
2a2c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a2d0 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
2a2e0 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
2a2f0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
2a300 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
2a310 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
2a320 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
2a330 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
2a340 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
2a350 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
2a360 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
2a370 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
2a380 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2a390 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
2a3a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a3b0 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
2a3c0 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
2a3d0 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
2a3e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2a3f0 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
2a400 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
2a410 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
2a420 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
2a430 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
2a440 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
2a450 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
2a460 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
2a470 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2a480 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
2a490 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
2a4a0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
2a4b0 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
2a4c0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
2a4d0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
2a4e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2a4f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
2a500 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2a510 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2a520 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2a530 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a540 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2a550 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
2a560 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
2a570 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
2a580 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
2a590 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2a5a0 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
2a5b0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2a5c0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
2a5d0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2a5e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2a5f0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
2a600 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2a610 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
2a620 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
2a630 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
2a640 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2a650 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
2a660 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
2a670 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
2a680 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2a690 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2a6a0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
2a6b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2a6c0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
2a6d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a6e0 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
2a6f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2a700 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
2a710 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2a720 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2a730 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
2a740 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
2a750 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a760 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
2a770 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
2a780 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
2a790 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
2a7a0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
2a7b0 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
2a7c0 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
2a7d0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
2a7e0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
2a7f0 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  vely..** ^SQLite
2a800 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
2a810 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
2a820 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
2a830 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
2a840 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
2a850 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a860 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
2a870 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
2a880 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2a890 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a8a0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2a8b0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2a8c0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2a8d0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
2a8e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2a8f0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
2a900 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
2a910 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
2a920 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2a930 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2a940 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2a950 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
2a960 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
2a970 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
2a980 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
2a990 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
2a9a0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2a9b0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2a9c0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
2a9d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a9e0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
2a9f0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
2aa00 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2aa10 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2aa20 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2aa30 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
2aa40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2aa50 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
2aa60 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
2aa70 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
2aa80 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
2aa90 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
2aaa0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
2aab0 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
2aac0 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
2aad0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
2aae0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
2aaf0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2ab00 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2ab10 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2ab20 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c  ces or to.** sql
2ab30 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2ab40 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
2ab50 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
2ab60 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
2ab70 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
2ab80 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
2ab90 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
2aba0 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
2abb0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
2abc0 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e   copy the conten
2abd0 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  t of the paramet
2abe0 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65  er nor call a de
2abf0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
2ac00 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  content.** when 
2ac10 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
2ac20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2ac30 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
2ac40 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2ac50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2ac60 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2ac70 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
2ac80 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
2ac90 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
2aca0 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
2acb0 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
2acc0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
2acd0 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
2ace0 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
2acf0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
2ad00 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2ad10 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
2ad20 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
2ad30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ad40 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
2ad50 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2ad60 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
2ad70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2ad80 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2ad90 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75  a copy the.** [u
2ada0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2adb0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2adc0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2add0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
2ade0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2adf0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2ae00 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
2ae10 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
2ae20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
2ae30 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73  * so that the [s
2ae40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70  qlite3_value] sp
2ae50 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70  ecified in the p
2ae60 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61  arameter may cha
2ae70 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61  nge or.** be dea
2ae80 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73  llocated after s
2ae90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2aea0 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69  lue() returns wi
2aeb0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
2aec0 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
2aed0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2aee0 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
2aef0 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
2af00 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2af10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2af20 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
2af30 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
2af40 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
2af50 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
2af60 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
2af70 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
2af80 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
2af90 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2afa0 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
2afb0 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
2afc0 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
2afd0 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
2afe0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2aff0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2b000 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
2b010 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
2b020 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
2b030 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2b040 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69  ndefined..*/.voi
2b050 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b060 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
2b070 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2b080 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2b090 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2b0a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
2b0b0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
2b0c0 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
2b0d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2b0e0 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
2b0f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2b100 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
2b110 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2b120 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
2b130 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2b140 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
2b150 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2b160 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
2b170 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
2b180 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
2b190 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
2b1a0 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
2b1b0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2b1c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b1d0 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
2b1e0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
2b1f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2b200 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
2b210 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
2b220 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2b230 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
2b240 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
2b250 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  e3_int64);.void 
2b260 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2b270 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
2b280 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
2b290 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2b2a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b2b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
2b2c0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2b2d0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2b2e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2b2f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b300 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2b310 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2b320 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2b330 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
2b340 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2b350 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2b360 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
2b370 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2b380 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2b390 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
2b3a0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2b3b0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
2b3c0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2b3d0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2b3e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b3f0 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
2b400 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2b410 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
2b420 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b430 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
2b440 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
2b450 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
2b460 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a   Sequences.**.**
2b470 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2b480 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2b490 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
2b4a0 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a  equences to the.
2b4b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
2b4c0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
2b4d0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
2b4e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2b4f0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2b500 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
2b510 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69  equence is speci
2b520 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20  fied as a UTF-8 
2b530 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
2b540 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2b550 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
2b560 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b570 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
2b580 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
2b590 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  g for sqlite3_cr
2b5a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2b5b0 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65  (). ^In all case
2b5c0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
2b5d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
2b5e0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2b5f0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2b600 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2b610 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nt may be one of
2b620 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
2b630 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
2b640 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2b650 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
2b660 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16BE], indicati
2b670 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72  ng that the user
2b680 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75  -supplied.** rou
2b690 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20  tine expects to 
2b6a0 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65  be passed pointe
2b6b0 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e  rs to strings en
2b6c0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
2b6d0 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  8,.** UTF-16 lit
2b6e0 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle-endian, or U
2b6f0 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
2b700 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
2b710 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72  ^The.** third ar
2b720 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73  gument might als
2b730 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  o be [SQLITE_UTF
2b740 31 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20  16] to indicate 
2b750 74 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65  that the routine
2b760 0a 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e  .** expects poin
2b770 74 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31  ters to be UTF-1
2b780 36 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  6 strings in the
2b790 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2b7a0 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72  er, or the.** ar
2b7b0 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53  gument can be [S
2b7c0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2b7d0 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74  NED] if the.** t
2b7e0 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  he routine expec
2b7f0 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31  ts pointers to 1
2b800 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e  6-bit word align
2b810 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66  ed strings.** of
2b820 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
2b830 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2b840 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ..**.** A pointe
2b850 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75  r to the user su
2b860 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d  pplied routine m
2b870 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
2b880 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72   the fifth.** ar
2b890 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74 20  gument.  ^If it 
2b8a0 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73  is NULL, this is
2b8b0 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c   the same as del
2b8c0 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74  eting the collat
2b8d0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
2b8e0 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20  (so that SQLite 
2b8f0 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61  cannot call it a
2b900 6e 79 20 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61  ny more)..** ^Ea
2b910 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
2b920 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
2b930 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
2b940 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
2b950 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
2b960 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
2b970 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
2b980 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2b990 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
2b9a0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
2b9b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
2b9c0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2b9d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
2b9e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61  .**.** ^The rema
2b9f0 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20  ining arguments 
2ba00 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
2ba10 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74  on-supplied rout
2ba20 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69  ine are two stri
2ba30 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70  ngs,.** each rep
2ba40 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c  resented by a (l
2ba50 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69  ength, data) pai
2ba60 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e  r and encoded in
2ba70 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a   the encoding.**
2ba80 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64   that was passed
2ba90 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72   as the third ar
2baa0 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20  gument when the 
2bab0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2bac0 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74  ce was.** regist
2bad0 65 72 65 64 2e 20 20 54 68 65 20 61 70 70 6c 69  ered.  The appli
2bae0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63  cation defined c
2baf0 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  ollation routine
2bb00 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
2bb10 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  n negative, zero
2bb20 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20   or positive if 
2bb30 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
2bb40 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a   is less than,.*
2bb50 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  * equal to, or g
2bb60 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
2bb70 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69  second string. i
2bb80 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53  .e. (STRING1 - S
2bb90 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e  TRING2)..**.** ^
2bba0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
2bbb0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2bbc0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
2bbd0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2bbe0 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70  ation().** excep
2bbf0 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
2bc00 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
2bc10 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
2bc20 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
2bc30 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e  he collation.  ^
2bc40 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2bc50 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  s called when th
2bc60 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a  e collation is.*
2bc70 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  * destroyed and 
2bc80 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
2bc90 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2bca0 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70  arameter void* p
2bcb0 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65  ointer.** of the
2bcc0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2bcd0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a  collation_v2()..
2bce0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61  ** ^Collations a
2bcf0 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65  re destroyed whe
2bd00 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
2bd10 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63  idden by later c
2bd20 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63  alls to the.** c
2bd30 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
2bd40 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
2bd50 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73  hen the [databas
2bd60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
2bd70 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67   closed.** using
2bd80 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2bd90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2bda0 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
2bdb0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2bdc0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2bdd0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2bde0 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
2bdf0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2be00 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
2be10 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
2be20 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
2be30 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2be40 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
2be50 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2be60 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2be70 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
2be80 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2be90 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
2bea0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2beb0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2bec0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
2bed0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
2bee0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2bef0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2bf00 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2bf10 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
2bf20 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
2bf30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2bf40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2bf50 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2bf60 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
2bf70 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
2bf80 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2bf90 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2bfa0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2bfb0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2bfc0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2bfd0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
2bfe0 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
2bff0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
2c000 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
2c010 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
2c020 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2c030 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
2c040 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
2c050 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
2c060 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
2c070 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
2c080 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
2c090 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2c0a0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2c0b0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
2c0c0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
2c0d0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
2c0e0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
2c0f0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
2c100 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
2c110 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
2c120 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2c130 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
2c140 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
2c150 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
2c160 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2c170 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
2c180 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
2c190 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
2c1a0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2c1b0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
2c1c0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
2c1d0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
2c1e0 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
2c1f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
2c200 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
2c210 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
2c220 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
2c230 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
2c240 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
2c250 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
2c260 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
2c270 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
2c280 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
2c290 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
2c2a0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2c2b0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
2c2c0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2c2d0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2c2e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2c2f0 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
2c300 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2c310 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2c320 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
2c330 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2c340 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2c350 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2c360 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
2c370 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
2c380 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
2c390 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
2c3a0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
2c3b0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2c3c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2c3d0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
2c3e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2c3f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
2c400 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
2c410 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
2c420 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2c430 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
2c440 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
2c450 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
2c460 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2c470 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c480 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
2c490 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2c4a0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
2c4b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2c4c0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
2c4d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2c4e0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
2c4f0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2c500 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
2c510 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2c520 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2c530 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
2c540 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2c550 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
2c560 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2c570 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
2c580 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2c590 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
2c5a0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
2c5b0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
2c5c0 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
2c5d0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
2c5e0 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
2c5f0 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
2c600 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
2c610 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
2c620 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
2c630 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2c640 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2c650 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2c660 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2c670 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2c680 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2c690 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2c6a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2c6b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c6c0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2c6d0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2c6e0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2c6f0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2c700 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2c710 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2c720 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2c730 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2c740 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2c750 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2c760 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2c770 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2c780 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2c790 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2c7a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2c7b0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2c7c0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2c7d0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2c7e0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2c7f0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2c800 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2c810 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2c820 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
2c830 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2c840 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c850 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2c860 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2c870 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2c880 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2c890 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
2c8a0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
2c8b0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
2c8c0 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
2c8d0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
2c8e0 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
2c8f0 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
2c900 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
2c910 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2c920 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
2c930 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2c940 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2c950 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2c960 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2c970 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
2c980 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
2c990 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2c9a0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2c9b0 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
2c9c0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
2c9d0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
2c9e0 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
2c9f0 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
2ca00 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2ca10 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
2ca20 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
2ca30 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
2ca40 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
2ca50 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
2ca60 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2ca70 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
2ca80 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
2ca90 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ort Time.**.** ^
2caa0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
2cab0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
2cac0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
2cad0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
2cae0 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
2caf0 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
2cb00 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2cb10 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
2cb20 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
2cb30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  .**.** ^If the o
2cb40 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
2cb50 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
2cb60 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
2cb70 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
2cb80 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
2cb90 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
2cba0 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
2cbb0 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
2cbc0 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
2cbd0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  ^The number of m
2cbe0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
2cbf0 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
2cc00 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
2cc10 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2cc20 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
2cc30 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
2cc40 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
2cc50 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
2cc60 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
2cc70 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
2cc80 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
2cc90 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
2cca0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ccb0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
2ccc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2ccd0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
2cce0 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
2ccf0 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
2cd00 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
2cd10 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
2cd20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
2cd30 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
2cd40 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
2cd50 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
2cd60 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
2cd70 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
2cd80 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
2cd90 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
2cda0 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
2cdb0 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
2cdc0 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
2cdd0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
2cde0 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
2cdf0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2ce00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2ce10 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
2ce20 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
2ce30 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
2ce40 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
2ce50 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
2ce60 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
2ce70 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2ce80 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2ce90 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
2cea0 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
2ceb0 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
2cec0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2ced0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2cee0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
2cef0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2cf00 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
2cf10 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
2cf20 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
2cf30 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
2cf40 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
2cf50 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
2cf60 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
2cf70 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
2cf80 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
2cf90 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
2cfa0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
2cfb0 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
2cfc0 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
2cfd0 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
2cfe0 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
2cff0 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
2d000 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
2d010 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
2d020 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2d030 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
2d040 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
2d050 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
2d060 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2d070 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2d080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
2d090 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
2d0a0 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
2d0b0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2d0c0 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
2d0d0 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
2d0e0 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
2d0f0 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
2d100 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
2d110 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2d120 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
2d130 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
2d140 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
2d150 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
2d160 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
2d170 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
2d180 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
2d190 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
2d1a0 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
2d1b0 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
2d1c0 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
2d1d0 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
2d1e0 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
2d1f0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2d200 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
2d210 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
2d220 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
2d230 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2d240 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
2d250 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oided..*/.SQLITE
2d260 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
2d270 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
2d280 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
2d290 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
2d2a0 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
2d2b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2d2c0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
2d2d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d2e0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
2d2f0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
2d300 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
2d310 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
2d320 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
2d330 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
2d340 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
2d350 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
2d360 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
2d370 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2d380 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
2d390 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
2d3a0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
2d3b0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
2d3c0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
2d3d0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2d3e0 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
2d3f0 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
2d400 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
2d410 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
2d420 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
2d430 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
2d440 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
2d450 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
2d460 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
2d470 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
2d480 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
2d490 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
2d4a0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
2d4b0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
2d4c0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
2d4d0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
2d4e0 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
2d4f0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
2d500 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
2d510 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
2d520 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
2d530 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
2d540 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2d550 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2d560 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
2d570 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
2d580 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
2d590 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
2d5a0 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
2d5b0 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
2d5c0 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
2d5d0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2d5e0 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
2d5f0 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
2d600 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
2d610 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
2d620 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
2d630 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
2d640 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
2d650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d660 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
2d670 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
2d680 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2d690 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  nt.**.** ^The sq
2d6a0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
2d6b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d6c0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2d6d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2d6e0 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
2d6f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d700 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
2d710 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63  ^The [database c
2d720 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
2d730 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2d740 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
2d750 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2d760 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
2d770 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
2d780 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
2d790 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2d7a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
2d7b0 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
2d7c0 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
2d7d0 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
2d7e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
2d7f0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
2d800 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
2d810 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
2d820 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2d830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d840 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
2d850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d860 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
2d870 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d880 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2d890 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
2d8a0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
2d8b0 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
2d8c0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
2d8d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d8e0 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
2d8f0 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
2d900 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
2d910 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2d920 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
2d930 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2d940 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
2d950 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
2d960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d970 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
2d980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2d990 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
2d9a0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
2d9b0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
2d9c0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
2d9d0 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
2d9e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
2d9f0 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
2da00 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2da10 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
2da20 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
2da30 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
2da40 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
2da50 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
2da60 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
2da70 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
2da80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
2da90 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
2daa0 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
2dab0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2dac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2dad0 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
2dae0 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
2daf0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
2db00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2db10 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
2db20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2db30 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
2db40 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
2db50 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2db60 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
2db70 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
2db80 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
2db90 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2dba0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2dbb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
2dbc0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
2dbd0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2dbe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2dbf0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2dc00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
2dc10 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
2dc20 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2dc30 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2dc40 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2dc50 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2dc60 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2dc70 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
2dc80 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
2dc90 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2dca0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2dcb0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
2dcc0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
2dcd0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2dce0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2dcf0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2dd00 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
2dd10 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
2dd20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
2dd30 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
2dd40 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
2dd50 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
2dd60 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
2dd70 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
2dd80 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
2dd90 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2dda0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2ddb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
2ddc0 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
2ddd0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
2dde0 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
2ddf0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
2de00 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
2de10 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
2de20 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
2de30 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
2de40 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
2de50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2de60 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
2de70 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
2de80 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
2de90 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
2dea0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
2deb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2dec0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2ded0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2dee0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2def0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2df00 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2df10 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
2df20 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
2df30 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2df40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
2df50 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
2df60 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
2df70 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
2df80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2df90 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
2dfa0 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
2dfb0 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
2dfc0 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
2dfd0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
2dfe0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
2dff0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2e000 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
2e010 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
2e020 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
2e030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
2e040 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
2e050 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
2e060 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
2e070 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
2e080 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
2e090 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
2e0a0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
2e0b0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
2e0c0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
2e0d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
2e0e0 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
2e0f0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
2e100 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
2e110 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
2e120 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
2e130 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
2e140 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
2e150 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
2e160 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
2e170 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
2e180 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
2e190 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
2e1a0 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
2e1b0 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
2e1c0 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
2e1d0 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
2e1e0 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
2e1f0 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
2e200 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
2e210 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
2e220 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
2e230 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
2e240 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
2e250 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
2e260 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
2e270 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
2e280 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
2e290 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
2e2a0 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
2e2b0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
2e2c0 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
2e2d0 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
2e2e0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
2e2f0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
2e300 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
2e310 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
2e320 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2e330 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
2e340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e350 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
2e360 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
2e370 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
2e380 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
2e390 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
2e3a0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2e3b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
2e3c0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
2e3d0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
2e3e0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
2e3f0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
2e400 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
2e410 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e420 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
2e430 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2e440 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
2e450 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2e460 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2e470 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2e480 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
2e490 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
2e4a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2e4b0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2e4c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
2e4d0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2e4e0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
2e4f0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2e500 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2e510 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2e520 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2e530 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
2e540 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
2e550 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2e560 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2e570 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
2e580 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2e590 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2e5a0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
2e5b0 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
2e5c0 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
2e5d0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2e5e0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2e5f0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2e600 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
2e610 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
2e620 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
2e630 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
2e640 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2e650 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
2e660 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
2e670 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2e680 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
2e690 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
2e6a0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
2e6b0 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
2e6c0 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
2e6d0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
2e6e0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
2e6f0 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
2e700 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2e710 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2e720 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2e730 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2e740 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
2e750 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
2e760 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2e770 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
2e780 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
2e790 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2e7a0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
2e7b0 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
2e7c0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
2e7d0 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
2e7e0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
2e7f0 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
2e800 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
2e810 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
2e820 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
2e830 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2e840 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
2e850 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
2e860 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
2e870 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
2e880 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
2e890 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
2e8a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
2e8b0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
2e8c0 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
2e8d0 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
2e8e0 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
2e8f0 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
2e900 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
2e910 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
2e920 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
2e930 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
2e940 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
2e950 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
2e960 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
2e970 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
2e980 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
2e990 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
2e9a0 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
2e9b0 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
2e9c0 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
2e9d0 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
2e9e0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
2e9f0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
2ea00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2ea10 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2ea20 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2ea30 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2ea40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2ea50 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2ea60 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
2ea70 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2ea80 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2ea90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2eaa0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2eab0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2eac0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2ead0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2eae0 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2eaf0 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
2eb00 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
2eb10 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
2eb20 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2eb30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
2eb40 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
2eb50 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
2eb60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
2eb70 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
2eb80 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
2eb90 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
2eba0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ebb0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
2ebc0 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
2ebd0 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
2ebe0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2ebf0 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
2ec00 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2ec10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ec20 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2ec30 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2ec40 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
2ec50 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
2ec60 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2ec70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2ec80 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2ec90 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
2eca0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2ecb0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
2ecc0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2ecd0 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
2ece0 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
2ecf0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
2ed00 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
2ed10 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
2ed20 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
2ed30 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
2ed40 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
2ed50 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
2ed60 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
2ed70 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
2ed80 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
2ed90 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
2eda0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
2edb0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
2edc0 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
2edd0 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
2ede0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
2edf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
2ee00 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
2ee10 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
2ee20 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
2ee30 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
2ee40 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
2ee50 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2ee60 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
2ee70 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
2ee80 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
2ee90 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
2eea0 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
2eeb0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
2eec0 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
2eed0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
2eee0 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
2eef0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
2ef00 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
2ef10 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
2ef20 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
2ef30 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
2ef40 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
2ef50 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
2ef60 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
2ef70 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
2ef80 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2ef90 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
2efa0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2efb0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
2efc0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2efd0 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
2efe0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2eff0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
2f000 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
2f010 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
2f020 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
2f030 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
2f040 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
2f050 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
2f060 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2f070 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
2f080 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
2f090 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
2f0a0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
2f0b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2f0c0 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
2f0d0 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
2f0e0 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
2f0f0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
2f100 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
2f110 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
2f120 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
2f130 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
2f140 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
2f150 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
2f160 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
2f170 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
2f180 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
2f190 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
2f1a0 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
2f1b0 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
2f1c0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
2f1d0 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
2f1e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2f1f0 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
2f200 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
2f210 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2f220 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
2f230 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2f240 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
2f250 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
2f260 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
2f270 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
2f280 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
2f290 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
2f2a0 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
2f2b0 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
2f2c0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2f2d0 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2f2e0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2f2f0 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2f300 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2f310 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2f320 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
2f330 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
2f340 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2f350 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
2f360 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
2f370 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
2f380 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
2f390 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
2f3a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f3b0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2f3c0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f   routine is a no
2f3d0 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65  -op returning ze
2f3e0 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  ro.** if SQLite 
2f3f0 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20  is not compiled 
2f400 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  with [SQLITE_ENA
2f410 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
2f420 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  EMENT]..*/.int s
2f430 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2f440 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  emory(int);../*.
2f450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70  ** CAPI3REF: Imp
2f460 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
2f470 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e  eap Size.**.** ^
2f480 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  The sqlite3_soft
2f490 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e  _heap_limit() in
2f4a0 74 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61  terface places a
2f4b0 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a   "soft" limit.**
2f4c0 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
2f4d0 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
2f4e0 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
2f4f0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
2f500 2a 20 5e 49 66 20 61 6e 20 69 6e 74 65 72 6e 61  * ^If an interna
2f510 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  l allocation is 
2f520 72 65 71 75 65 73 74 65 64 20 74 68 61 74 20 77  requested that w
2f530 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a  ould exceed the.
2f540 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  ** soft heap lim
2f550 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  it, [sqlite3_rel
2f560 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
2f570 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72  s invoked one or
2f580 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74  .** more times t
2f590 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73  o free up some s
2f5a0 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20  pace before the 
2f5b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65  allocation is pe
2f5c0 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  rformed..**.** ^
2f5d0 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c  The limit is cal
2f5e0 6c 65 64 20 22 73 6f 66 74 22 20 62 65 63 61 75  led "soft" becau
2f5f0 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72  se if [sqlite3_r
2f600 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
2f610 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20  .** cannot free 
2f620 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
2f630 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65  y to prevent the
2f640 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e   limit from bein
2f650 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74  g exceeded,.** t
2f660 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  he memory is all
2f670 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e  ocated anyway an
2f680 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70  d the current op
2f690 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
2f6a0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  ..**.** ^A negat
2f6b0 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75  ive or zero valu
2f6c0 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68  e for N means th
2f6d0 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73  at there is no s
2f6e0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61  oft heap limit a
2f6f0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  nd.** [sqlite3_r
2f700 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
2f710 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61   will only be ca
2f720 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
2f730 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
2f740 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 76  * ^The default v
2f750 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66  alue for the sof
2f760 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
2f770 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51  zero..**.** ^(SQ
2f780 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73  Lite makes a bes
2f790 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f  t effort to hono
2f7a0 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
2f7b0 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66  limit..** But if
2f7c0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2f7d0 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68  imit cannot be h
2f7e0 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f  onored, executio
2f7f0 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e  n will.** contin
2f800 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72  ue without error
2f810 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e   or notification
2f820 2e 29 5e 20 20 54 68 69 73 20 69 73 20 77 68 79  .)^  This is why
2f830 20 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a   the limit is.**
2f840 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22   called a "soft"
2f850 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61   limit.  It is a
2f860 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a  dvisory only..**
2f870 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
2f880 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
2f890 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  0, this routine 
2f8a0 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64  only constrained
2f8b0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
2f8c0 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69  llocated by a si
2f8d0 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68  ngle thread - th
2f8e0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2f8f0 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74   which this rout
2f900 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65  ine.** runs.  Be
2f910 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
2f920 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
2f930 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  0, the soft heap
2f940 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70   limit is.** app
2f950 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65  lied to all thre
2f960 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73  ads. The value s
2f970 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65  pecified for the
2f980 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2f990 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20  .** is an upper 
2f9a0 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74  bound on the tot
2f9b0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
2f9c0 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72  tion for all thr
2f9d0 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73  eads. In.** vers
2f9e0 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20  ion 3.5.0 there 
2f9f0 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
2fa00 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65  for limiting the
2fa10 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a   heap usage for.
2fa20 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68  ** individual th
2fa30 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  reads..*/.void s
2fa40 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
2fa50 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a  _limit(int);../*
2fa60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
2fa70 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
2fa80 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
2fa90 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e   A Table.**.** ^
2faa0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2fab0 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62  urns metadata ab
2fac0 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63  out a specific c
2fad0 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69  olumn of a speci
2fae0 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  fic.** database 
2faf0 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65  table accessible
2fb00 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61   using the [data
2fb10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2fb20 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65   handle.** passe
2fb30 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
2fb40 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2fb50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
2fb60 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
2fb70 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
2fb80 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
2fb90 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a  h parameters to.
2fba0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
2fbb0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2fbc0 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65  rameter is eithe
2fbd0 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  r the name of th
2fbe0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69  e database.** (i
2fbf0 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  .e. "main", "tem
2fc00 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68  p", or an attach
2fc10 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
2fc20 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
2fc30 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
2fc40 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69  r NULL. ^If it i
2fc50 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
2fc60 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2fc70 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
2fc80 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
2fc90 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
2fca0 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20   algorithm used 
2fcb0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
2fcc0 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  engine to.** res
2fcd0 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
2fce0 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
2fcf0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  s..**.** ^The th
2fd00 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
2fd10 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2fd20 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
2fd30 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
2fd40 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
2fd50 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
2fd60 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2fd70 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
2fd80 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
2fd90 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
2fda0 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20  ** ^Metadata is 
2fdb0 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
2fdc0 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
2fdd0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
2fde0 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a  ed as the 5th.**
2fdf0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
2fe00 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
2fe10 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e  is function. ^An
2fe20 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d  y of these argum
2fe30 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e  ents may be.** N
2fe40 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
2fe50 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
2fe60 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
2fe70 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74  metadata is omit
2fe80 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c  ted..**.** ^(<bl
2fe90 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2fea0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2feb0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61  ** <tr><th> Para
2fec0 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75  meter <th> Outpu
2fed0 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  t<br>Type <th>  
2fee0 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a  Description.**.*
2fef0 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c  * <tr><td> 5th <
2ff00 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
2ff10 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a  <td> Data type.*
2ff20 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c  * <tr><td> 6th <
2ff30 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
2ff40 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66  <td> Name of def
2ff50 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
2ff60 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c  equence.** <tr><
2ff70 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74  td> 7th <td> int
2ff80 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
2ff90 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73  ue if column has
2ffa0 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
2ffb0 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74  traint.** <tr><t
2ffc0 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 8th <td> int 
2ffd0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
2ffe0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70  e if column is p
2fff0 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
30000 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74  RY KEY.** <tr><t
30010 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 9th <td> int 
30020 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
30030 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b  e if column is [
30040 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a  AUTOINCREMENT].*
30050 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
30060 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
30070 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
30080 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
30090 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
300a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
300b0 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61  r the.** declara
300c0 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
300d0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
300e0 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
300f0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a  ntil the next.**
30100 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c   call to any SQL
30110 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
30120 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
30130 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
30140 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
30150 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ew, an [error co
30160 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
30170 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
30180 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
30190 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
301a0 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
301b0 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45  nd an.** [INTEGE
301c0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
301d0 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
301e0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
301f0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
30200 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
30210 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
30220 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
30230 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28  lared column. ^(
30240 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a  If there is no.*
30250 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  * explicitly dec
30260 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50  lared [INTEGER P
30270 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
30280 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  mn, then the out
30290 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
302a0 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c  s are set as fol
302b0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  lows:.**.** <pre
302c0 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79  >.**     data ty
302d0 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a  pe: "INTEGER".**
302e0 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73       collation s
302f0 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59  equence: "BINARY
30300 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c  ".**     not nul
30310 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d  l: 0.**     prim
30320 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20  ary key: 1.**   
30330 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74    auto increment
30340 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  : 0.** </pre>)^.
30350 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
30360 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
30370 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
30380 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
30390 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
303a0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
303b0 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
303c0 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
303d0 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
303e0 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
303f0 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65   be found, an [e
30400 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
30410 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
30420 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74  ror message left
30430 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61  .** in the [data
30440 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30450 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
30460 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
30470 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a  errmsg()).)^.**.
30480 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20  ** ^This API is 
30490 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
304a0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
304b0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
304c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
304d0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
304e0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
304f0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
30500 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
30510 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
30520 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
30530 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
30540 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
30550 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
30560 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
30570 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
30580 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
30590 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
305a0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
305b0 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
305c0 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
305d0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
305e0 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
305f0 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
30600 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
30610 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
30620 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
30630 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
30640 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
30650 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
30660 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
30670 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
30680 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
30690 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
306a0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
306b0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
306c0 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
306d0 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
306e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
306f0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
30700 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
30710 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
30720 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
30730 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
30740 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75   if column is au
30750 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
30760 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30770 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
30780 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  nsion.**.** ^Thi
30790 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64  s interface load
307a0 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  s an SQLite exte
307b0 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72  nsion library fr
307c0 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c  om the named fil
307d0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e..**.** ^The sq
307e0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
307f0 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
30800 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61   attempts to loa
30810 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65  d an.** SQLite e
30820 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
30830 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
30840 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a  e file zFile..**
30850 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70  .** ^The entry p
30860 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a  oint is zProc..*
30870 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20  * ^zProc may be 
30880 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  0, in which case
30890 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
308a0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
308b0 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c  defaults to "sql
308c0 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
308d0 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nit"..** ^The sq
308e0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
308f0 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
30900 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
30910 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
30920 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45  ss and [SQLITE_E
30930 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69  RROR] if somethi
30940 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
30950 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  * ^If an error o
30960 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
30970 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
30980 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  n the.** [sqlite
30990 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
309a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  ()] interface sh
309b0 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a  all attempt to.*
309c0 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67  * fill *pzErrMsg
309d0 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73   with error mess
309e0 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20  age text stored 
309f0 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74  in memory.** obt
30a00 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
30a10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54  te3_malloc()]. T
30a20 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
30a30 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72  ion.** should fr
30a40 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62  ee this memory b
30a50 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
30a60 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
30a70 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
30a80 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61  ding must be ena
30a90 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  bled using.** [s
30aa0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
30ab0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
30ac0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
30ad0 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74   this API,.** ot
30ae0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
30af0 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
30b00 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
30b10 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  o the [load_exte
30b20 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63  nsion() SQL func
30b30 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  tion]..*/.int sq
30b40 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
30b50 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  sion(.  sqlite3 
30b60 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
30b70 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73   Load the extens
30b80 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61  ion into this da
30b90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30ba0 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
30bb0 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20  r *zFile,    /* 
30bc0 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72  Name of the shar
30bd0 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  ed library conta
30be0 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20  ining extension 
30bf0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
30c00 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e  *zProc,    /* En
30c10 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69  try point.  Deri
30c20 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69  ved from zFile i
30c30 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  f 0 */.  char **
30c40 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f  pzErrMsg       /
30c50 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73  * Put error mess
30c60 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20  age here if not 
30c70 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  0 */.);../*.** C
30c80 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
30c90 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
30ca0 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
30cb0 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f  ** ^So as not to
30cc0 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68   open security h
30cd0 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70  oles in older ap
30ce0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
30cf0 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65  are.** unprepare
30d00 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65  d to deal with e
30d10 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
30d20 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73  , and as a means
30d30 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a   of disabling.**
30d40 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
30d50 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74  ng while evaluat
30d60 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64  ing user-entered
30d70 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77   SQL, the follow
30d80 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72  ing API.** is pr
30d90 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74  ovided to turn t
30da0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
30db0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65  _extension()] me
30dc0 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f  chanism on and o
30dd0 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  ff..**.** ^Exten
30de0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20  sion loading is 
30df0 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20  off by default. 
30e00 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33  See ticket #1863
30e10 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73  ..** ^Call the s
30e20 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
30e30 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72  ad_extension() r
30e40 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66  outine with onof
30e50 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20  f==1.** to turn 
30e60 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
30e70 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74  g on and call it
30e80 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74   with onoff==0 t
30e90 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63  o turn.** it bac
30ea0 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a  k off again..*/.
30eb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
30ec0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
30ed0 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69  n(sqlite3 *db, i
30ee0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
30ef0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f  * CAPI3REF: Auto
30f00 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41  matically Load A
30f10 6e 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a  n Extensions.**.
30f20 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 63 61 6e  ** ^This API can
30f30 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70   be invoked at p
30f40 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69  rogram startup i
30f50 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73  n order to regis
30f60 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
30f70 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69  re statically li
30f80 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20  nked extensions 
30f90 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61  that will be ava
30fa0 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c  ilable.** to all
30fb0 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
30fc0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a  onnections]..**.
30fd0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
30fe0 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74  e stores a point
30ff0 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73  er to the extens
31000 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  ion entry point.
31010 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 74  ** in an array t
31020 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  hat is obtained 
31030 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
31040 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 61 74 20 6d  lloc()].  That m
31050 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 64 65 61 6c  emory.** is deal
31060 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69  located by [sqli
31070 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
31080 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 29 5e 0a 2a  xtension()].)^.*
31090 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
310a0 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e  ion registers an
310b0 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79   extension entry
310c0 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a   point that is.*
310d0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
310e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
310f0 20 61 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65   a new [database
31100 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
31110 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20  is opened using 
31120 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
31130 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
31140 36 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  6()],.** or [sql
31150 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
31160 0a 2a 2a 20 5e 44 75 70 6c 69 63 61 74 65 20 65  .** ^Duplicate e
31170 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65  xtensions are de
31180 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e  tected so callin
31190 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  g this routine.*
311a0 2a 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  * multiple times
311b0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65   with the same e
311c0 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d  xtension is harm
311d0 6c 65 73 73 2e 0a 2a 2a 20 5e 41 75 74 6f 6d 61  less..** ^Automa
311e0 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  tic extensions a
311f0 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  pply across all 
31200 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20  threads..*/.int 
31210 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
31220 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45  ension(void (*xE
31230 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29  ntryPoint)(void)
31240 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31250 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
31260 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
31270 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ading.**.** ^(Th
31280 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  is function disa
31290 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75  bles all previou
312a0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61  sly registered a
312b0 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65  utomatic.** exte
312c0 6e 73 69 6f 6e 73 2e 20 49 74 20 75 6e 64 6f 65  nsions. It undoe
312d0 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
312e0 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71  all prior.** [sq
312f0 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
31300 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 29 5e  sion()] calls.)^
31310 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
31320 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
31330 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
31340 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61  ons in all threa
31350 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ds..*/.void sqli
31360 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
31370 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  xtension(void);.
31380 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
31390 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
313a0 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
313b0 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ism is currently
313c0 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
313d0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
313e0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
313f0 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
31400 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
31410 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
31420 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
31430 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
31440 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
31450 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
31460 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
31470 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
31480 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20  ism stabilizes, 
31490 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
314a0 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
314b0 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
314c0 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
314d0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
314e0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a   comment..*/../*
314f0 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75  .** Structures u
31500 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75  sed by the virtu
31510 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
31520 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ce.*/.typedef st
31530 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
31540 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a  b sqlite3_vtab;.
31550 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
31560 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
31570 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  o sqlite3_index_
31580 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74  info;.typedef st
31590 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
315a0 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33  b_cursor sqlite3
315b0 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79  _vtab_cursor;.ty
315c0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
315d0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69  ite3_module sqli
315e0 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a  te3_module;../*.
315f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
31600 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63  tual Table Objec
31610 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
31620 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76  qlite3_module {v
31630 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
31640 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ule}.**.** This 
31650 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74  structure, somet
31660 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20  imes called a a 
31670 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  "virtual table m
31680 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69  odule", .** defi
31690 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nes the implemen
316a0 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72  tation of a [vir
316b0 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a  tual tables].  .
316c0 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
316d0 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c  e consists mostl
316e0 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72  y of methods for
316f0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
31700 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61  ** ^A virtual ta
31710 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72  ble module is cr
31720 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67  eated by filling
31730 20 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74   in a persistent
31740 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
31750 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61  this structure a
31760 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69  nd passing a poi
31770 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73  nter to that ins
31780 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c  tance.** to [sql
31790 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
317a0 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  le()] or [sqlite
317b0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
317c0 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  v2()]..** ^The r
317d0 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61  egistration rema
317e0 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  ins valid until 
317f0 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20 62  it is replaced b
31800 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  y a different.**
31810 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c   module or until
31820 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
31830 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65  onnection] close
31840 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a  s.  The content.
31850 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ** of this struc
31860 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68  ture must not ch
31870 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69 73  ange while it is
31880 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
31890 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65  .** any database
318a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a   connection..*/.
318b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
318c0 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56  odule {.  int iV
318d0 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
318e0 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33  xCreate)(sqlite3
318f0 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
31900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
31910 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
31920 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
31930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
31940 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
31950 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
31960 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29   int (*xConnect)
31970 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
31980 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
31990 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
319a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
319b0 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
319c0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
319d0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
319e0 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
319f0 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74  BestIndex)(sqlit
31a00 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
31a10 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
31a20 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  fo*);.  int (*xD
31a30 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  isconnect)(sqlit
31a40 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
31a50 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f  .  int (*xDestro
31a60 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  y)(sqlite3_vtab 
31a70 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
31a80 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
31a90 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
31aa0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
31ab0 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20   **ppCursor);.  
31ac0 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
31ad0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
31ae0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  r*);.  int (*xFi
31af0 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
31b00 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
31b10 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
31b20 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20  ar *idxStr,.    
31b30 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
31b40 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61  argc, sqlite3_va
31b50 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69  lue **argv);.  i
31b60 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69  nt (*xNext)(sqli
31b70 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
31b80 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29  );.  int (*xEof)
31b90 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
31ba0 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
31bb0 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33  xColumn)(sqlite3
31bc0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
31bd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31be0 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
31bf0 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76  Rowid)(sqlite3_v
31c00 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
31c10 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77  ite3_int64 *pRow
31c20 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70  id);.  int (*xUp
31c30 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74  date)(sqlite3_vt
31c40 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  ab *, int, sqlit
31c50 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c  e3_value **, sql
31c60 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20  ite3_int64 *);. 
31c70 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73   int (*xBegin)(s
31c80 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
31c90 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ab);.  int (*xSy
31ca0 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  nc)(sqlite3_vtab
31cb0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
31cc0 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74  (*xCommit)(sqlit
31cd0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
31ce0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61  .  int (*xRollba
31cf0 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ck)(sqlite3_vtab
31d00 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
31d10 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29  (*xFindFunction)
31d20 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
31d30 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20  Vtab, int nArg, 
31d40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
31d50 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  e,.             
31d60 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28            void (
31d70 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65  **pxFunc)(sqlite
31d80 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31d90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31da0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
31db0 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70          void **p
31dc0 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
31dd0 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  Rename)(sqlite3_
31de0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e  vtab *pVtab, con
31df0 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a  st char *zNew);.
31e00 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
31e10 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
31e20 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72  e Indexing Infor
31e30 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52  mation.** KEYWOR
31e40 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  DS: sqlite3_inde
31e50 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65  x_info.**.** The
31e60 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
31e70 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e  nfo structure an
31e80 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75  d its substructu
31e90 72 65 73 20 69 73 20 75 73 65 64 20 61 73 20 70  res is used as p
31ea0 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76  art.** of the [v
31eb0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 69 6e  irtual table] in
31ec0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 70 61  terface to.** pa
31ed0 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ss information i
31ee0 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20  nto and receive 
31ef0 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74  the reply from t
31f00 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a  he [xBestIndex].
31f10 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b  ** method of a [
31f20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
31f30 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c  dule].  The fiel
31f40 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74  ds under **Input
31f50 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69  s** are the.** i
31f60 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e  nputs to xBestIn
31f70 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64  dex and are read
31f80 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64  -only.  xBestInd
31f90 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a  ex inserts its.*
31fa0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74  * results into t
31fb0 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66  he **Outputs** f
31fc0 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ields..**.** ^(T
31fd0 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
31fe0 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57   array records W
31ff0 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
32000 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66  traints of the f
32010 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  orm:.**.** <bloc
32020 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20 4f 50  kquote>column OP
32030 20 65 78 70 72 3c 2f 62 6c 6f 63 6b 71 75 6f 74   expr</blockquot
32040 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f  e>.**.** where O
32050 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c  P is =, &lt;, &l
32060 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67  t;=, &gt;, or &g
32070 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61  t;=.)^  ^(The pa
32080 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f  rticular operato
32090 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69  r is.** stored i
320a0 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
320b0 6f 70 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  op using one of 
320c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
320d0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
320e0 45 51 20 7c 20 53 51 4c 49 54 45 5f 49 4e 44 45  EQ | SQLITE_INDE
320f0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 20 76 61  X_CONSTRAINT_ va
32100 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28 54 68  lues].)^.** ^(Th
32110 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
32120 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20  olumn is stored 
32130 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e  in.** aConstrain
32140 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20  t[].iColumn.)^  
32150 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  ^(aConstraint[].
32160 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69  usable is TRUE i
32170 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e  f the.** expr on
32180 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
32190 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c  side can be eval
321a0 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20  uated (and thus 
321b0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  the constraint.*
321c0 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64  * is usable) and
321d0 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e   false if it can
321e0 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  not.)^.**.** ^Th
321f0 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f  e optimizer auto
32200 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74  matically invert
32210 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66  s terms of the f
32220 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c  orm "expr OP col
32230 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65  umn".** and make
32240 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69  s other simplifi
32250 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57  cations to the W
32260 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61  HERE clause in a
32270 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20  n attempt to.** 
32280 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52  get as many WHER
32290 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69  E clause terms i
322a0 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f  nto the form sho
322b0 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73  wn above as poss
322c0 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43  ible..** ^The aC
322d0 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
322e0 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57  y only reports W
322f0 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
32300 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 72 65  s that are.** re
32310 6c 65 76 61 6e 74 20 74 6f 20 74 68 65 20 70 61  levant to the pa
32320 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
32330 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
32340 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66  ried..**.** ^Inf
32350 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
32360 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
32370 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  se is stored in 
32380 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e  aOrderBy[]..** ^
32390 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72  Each term of aOr
323a0 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20  derBy records a 
323b0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52  column of the OR
323c0 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a  DER BY clause..*
323d0 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49  *.** The [xBestI
323e0 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73  ndex] method mus
323f0 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69  t fill aConstrai
32400 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69  ntUsage[] with i
32410 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
32420 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74  out what paramet
32430 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78  ers to pass to x
32440 46 69 6c 74 65 72 2e 20 20 5e 49 66 20 61 72 67  Filter.  ^If arg
32450 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a  vIndex>0 then.**
32460 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
32470 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72  side of the corr
32480 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74  esponding aConst
32490 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75  raint[] is evalu
324a0 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f  ated.** and beco
324b0 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65  mes the argvInde
324c0 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72  x-th entry in ar
324d0 67 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73 74  gv.  ^(If aConst
324e0 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69  raintUsage[].omi
324f0 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68  t.** is true, th
32500 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  en the constrain
32510 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20  t is assumed to 
32520 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64  be fully handled
32530 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75   by the.** virtu
32540 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20  al table and is 
32550 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69  not checked agai
32560 6e 20 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a 2a  n by SQLite.)^.*
32570 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75 6d  *.** ^The idxNum
32580 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75   and idxPtr valu
32590 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20  es are recorded 
325a0 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20  and passed into 
325b0 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d  the.** [xFilter]
325c0 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71   method..** ^[sq
325d0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
325e0 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64   used to free id
325f0 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79  xPtr if and only
32600 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65   if.** needToFre
32610 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65 2e  eIdxPtr is true.
32620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65  .**.** ^The orde
32630 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e  rByConsumed mean
32640 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72  s that output fr
32650 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e  om [xFilter]/[xN
32660 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20  ext] will occur 
32670 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63  in.** the correc
32680 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73  t order to satis
32690 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  fy the ORDER BY 
326a0 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e  clause so that n
326b0 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f  o separate.** so
326c0 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65  rting step is re
326d0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
326e0 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  he estimatedCost
326f0 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74   value is an est
32700 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73  imate of the cos
32710 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a  t of doing the.*
32720 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f  * particular loo
32730 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61  kup.  A full sca
32740 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74  n of a table wit
32750 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  h N entries shou
32760 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73  ld have.** a cos
32770 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72  t of N.  A binar
32780 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61  y search of a ta
32790 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73  ble of N entries
327a0 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a   should have a.*
327b0 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78  * cost of approx
327c0 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a  imately log(N)..
327d0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
327e0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20  3_index_info {. 
327f0 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20   /* Inputs */.  
32800 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b  int nConstraint;
32810 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
32820 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20  mber of entries 
32830 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a  in aConstraint *
32840 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
32850 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
32860 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  int {.     int i
32870 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
32880 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f       /* Column o
32890 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  n left-hand side
328a0 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a   of constraint *
328b0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
328c0 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20  char op;        
328d0 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f   /* Constraint o
328e0 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20  perator */.     
328f0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73  unsigned char us
32900 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75  able;     /* Tru
32910 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72  e if this constr
32920 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a  aint is usable *
32930 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d  /.     int iTerm
32940 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20  Offset;         
32950 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61   /* Used interna
32960 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78  lly - xBestIndex
32970 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a   should ignore *
32980 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
32990 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  nt;            /
329a0 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45  * Table of WHERE
329b0 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
329c0 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72  nts */.  int nOr
329d0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
329e0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
329f0 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52   terms in the OR
32a00 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
32a10 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
32a20 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20  3_index_orderby 
32a30 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
32a40 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
32a50 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65   /* Column numbe
32a60 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
32a70 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20  ed char desc;   
32a80 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20      /* True for 
32a90 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72  DESC.  False for
32aa0 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f   ASC. */.  } *aO
32ab0 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
32ac0 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44        /* The ORD
32ad0 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
32ae0 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a    /* Outputs */.
32af0 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
32b00 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
32b10 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e  t_usage {.    in
32b20 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20  t argvIndex;    
32b30 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c         /* if >0,
32b40 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70   constraint is p
32b50 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78  art of argv to x
32b60 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e  Filter */.    un
32b70 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74  signed char omit
32b80 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74  ;      /* Do not
32b90 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72   code a test for
32ba0 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
32bb0 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
32bc0 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74  aintUsage;.  int
32bd0 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20   idxNum;        
32be0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
32bf0 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69  r used to identi
32c00 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a  fy the index */.
32c10 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20    char *idxStr; 
32c20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32c30 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79  String, possibly
32c40 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
32c50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f  qlite3_malloc */
32c60 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65  .  int needToFre
32c70 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a  eIdxStr;      /*
32c80 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69   Free idxStr usi
32c90 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
32ca0 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69  ) if true */.  i
32cb0 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  nt orderByConsum
32cc0 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  ed;       /* Tru
32cd0 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61  e if output is a
32ce0 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a  lready ordered *
32cf0 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d  /.  double estim
32d00 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f  atedCost;      /
32d10 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74  * Estimated cost
32d20 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69   of using this i
32d30 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ndex */.};../*.*
32d40 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
32d50 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e 73 74 72  ual Table Constr
32d60 61 69 6e 74 20 4f 70 65 72 61 74 6f 72 20 43 6f  aint Operator Co
32d70 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  des.**.** These 
32d80 6d 61 63 72 6f 73 20 64 65 66 69 6e 65 64 20 74  macros defined t
32d90 68 65 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  he allowed value
32da0 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71  s for the.** [sq
32db0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
32dc0 5d 2e 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  ].aConstraint[].
32dd0 6f 70 20 66 69 65 6c 64 2e 20 20 45 61 63 68 20  op field.  Each 
32de0 76 61 6c 75 65 20 72 65 70 72 65 73 65 6e 74 73  value represents
32df0 0a 2a 2a 20 61 6e 20 6f 70 65 72 61 74 6f 72 20  .** an operator 
32e00 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20  that is part of 
32e10 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 74 65 72  a constraint ter
32e20 6d 20 69 6e 20 74 68 65 20 77 48 45 52 45 20 63  m in the wHERE c
32e30 6c 61 75 73 65 20 6f 66 0a 2a 2a 20 61 20 71 75  lause of.** a qu
32e40 65 72 79 20 74 68 61 74 20 75 73 65 73 20 61 20  ery that uses a 
32e50 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e  [virtual table].
32e60 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
32e70 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
32e80 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
32e90 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
32ea0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
32eb0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
32ec0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
32ed0 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
32ee0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
32ef0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
32f00 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
32f10 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
32f20 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
32f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
32f40 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
32f50 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41  TCH 64../*.** CA
32f60 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
32f70 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
32f80 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   Implementation.
32f90 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
32fa0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
32fb0 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
32fc0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
32fd0 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a  module] name..**
32fe0 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d   ^Module names m
32ff0 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
33000 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61  d before.** crea
33010 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74  ting a new [virt
33020 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67  ual table] using
33030 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20   the module and 
33040 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a  before using a.*
33050 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76  * preexisting [v
33060 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f  irtual table] fo
33070 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
33080 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20  .** ^The module 
33090 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 72  name is register
330a0 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ed on the [datab
330b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
330c0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
330d0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
330e0 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20  ter.  ^The name 
330f0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73  of the module is
33100 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a   given by the .*
33110 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
33120 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  er.  ^The third 
33130 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
33140 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ointer to.** the
33150 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33160 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
33170 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
33180 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20   ^The fourth.** 
33190 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
331a0 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74  arbitrary client
331b0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
331c0 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  at is passed thr
331d0 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  ough.** into the
331e0 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b   [xCreate] and [
331f0 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64  xConnect] method
33200 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  s of the virtual
33210 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a   table module.**
33220 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74   when a new virt
33230 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20  ual table is be 
33240 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72  being created or
33250 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a   reinitialized..
33260 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33270 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
33280 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
33290 68 61 73 20 61 20 66 69 66 74 68 20 70 61 72 61  has a fifth para
332a0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
332b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
332c0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
332d0 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e  the pClientData.
332e0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a    ^SQLite will.*
332f0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  * invoke the des
33300 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
33310 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   (if it is not N
33320 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65  ULL) when SQLite
33330 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65  .** no longer ne
33340 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44  eds the pClientD
33350 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ata pointer.  ^T
33360 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
33370 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e  e_module().** in
33380 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76  terface is equiv
33390 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  alent to sqlite3
333a0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
333b0 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a  2() with a NULL.
333c0 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a  ** destructor..*
333d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
333e0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
333f0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
33400 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
33410 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
33420 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
33430 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
33440 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
33450 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
33460 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
33470 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
33480 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
33490 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
334a0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
334b0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
334c0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
334d0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
334e0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
334f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
33500 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20  ate_module_v2(. 
33510 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
33520 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
33530 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
33540 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
33550 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
33560 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
33570 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
33580 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
33590 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
335a0 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
335b0 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
335c0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
335d0 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c  id *pClientData,
335e0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
335f0 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
33600 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
33610 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
33620 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20  )(void*)     /* 
33630 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f  Module destructo
33640 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b  r function */.);
33650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33660 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
33670 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a  Instance Object.
33680 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
33690 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20  ite3_vtab.**.** 
336a0 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
336b0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
336c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
336d0 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f   a subclass.** o
336e0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f  f this object to
336f0 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
33700 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a  icular instance.
33710 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  ** of the [virtu
33720 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68  al table].  Each
33730 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
33740 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
33750 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
33760 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
33770 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
33780 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65  ..** The purpose
33790 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c   of this supercl
337a0 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65  ass is to define
337b0 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20   certain fields 
337c0 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d  that are.** comm
337d0 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65  on to all module
337e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
337f0 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c  ..**.** ^Virtual
33800 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
33810 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
33820 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
33830 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
33840 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
33850 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
33860 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ()] to zErrMsg. 
33870 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
33880 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
33890 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
338a0 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
338b0 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
338c0 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
338d0 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69  prior to assigni
338e0 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20  ng a new string 
338f0 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66  to zErrMsg.  ^Af
33900 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
33910 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
33920 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
33930 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
33940 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
33950 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
33960 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
33970 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
33980 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
33990 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
339a0 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  roed..*/.struct 
339b0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20  sqlite3_vtab {. 
339c0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
339d0 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20  odule *pModule; 
339e0 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66   /* The module f
339f0 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  or this virtual 
33a00 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e  table */.  int n
33a10 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20  Ref;            
33a20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f             /* NO
33a30 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a   LONGER USED */.
33a40 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b    char *zErrMsg;
33a50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33a60 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61    /* Error messa
33a70 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ge from sqlite3_
33a80 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f  mprintf() */.  /
33a90 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
33aa0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
33ab0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
33ac0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
33ad0 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
33ae0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
33af0 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72  ual Table Cursor
33b00 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
33b10 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
33b20 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61  b_cursor {virtua
33b30 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a  l table cursor}.
33b40 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
33b50 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
33b60 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
33b70 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
33b80 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  s of the.** foll
33b90 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20  owing structure 
33ba0 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73  to describe curs
33bb0 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69  ors that point i
33bc0 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74  nto the.** [virt
33bd0 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61  ual table] and a
33be0 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
33bf0 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
33c00 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
33c10 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
33c20 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
33c30 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
33c40 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d  xOpen | xOpen] m
33c50 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
33c60 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74  ule and are dest
33c70 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  royed.** by the 
33c80 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
33c90 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d  xClose | xClose]
33ca0 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72   method.  Cursor
33cb0 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79  s are used.** by
33cc0 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20   the [xFilter], 
33cd0 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c  [xNext], [xEof],
33ce0 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20   [xColumn], and 
33cf0 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73  [xRowid] methods
33d00 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  .** of the modul
33d10 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  e.  Each module 
33d20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
33d30 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68  ill define.** th
33d40 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63  e content of a c
33d50 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20  ursor structure 
33d60 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20  to suit its own 
33d70 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  needs..**.** Thi
33d80 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69  s superclass exi
33d90 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  sts in order to 
33da0 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66  define fields of
33db0 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74   the cursor that
33dc0 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74  .** are common t
33dd0 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61  o all implementa
33de0 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74  tions..*/.struct
33df0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
33e00 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33  rsor {.  sqlite3
33e10 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20  _vtab *pVtab;   
33e20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61     /* Virtual ta
33e30 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73  ble of this curs
33e40 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  or */.  /* Virtu
33e50 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
33e60 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
33e70 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
33e80 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
33e90 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
33ea0 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65  REF: Declare The
33eb0 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72   Schema Of A Vir
33ec0 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  tual Table.**.**
33ed0 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20   ^The [xCreate] 
33ee0 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d  and [xConnect] m
33ef0 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b  ethods of a.** [
33f00 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
33f10 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20  dule] call this 
33f20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
33f30 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
33f40 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
33f50 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
33f60 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
33f70 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
33f80 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
33f90 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
33fa0 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
33fb0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
33fc0 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f   char *zSQL);../
33fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
33fe0 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69  verload A Functi
33ff0 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c  on For A Virtual
34000 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56   Table.**.** ^(V
34010 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
34020 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e  n provide altern
34030 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
34040 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f  tions of functio
34050 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ns.** using the 
34060 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20  [xFindFunction] 
34070 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76  method of the [v
34080 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
34090 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67  ule].  .** But g
340a0 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f  lobal versions o
340b0 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e  f those function
340c0 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20  s.** must exist 
340d0 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f  in order to be o
340e0 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a  verloaded.)^.**.
340f0 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61  ** ^(This API ma
34100 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
34110 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
34120 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
34130 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
34140 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
34150 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
34160 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
34170 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
34180 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
34190 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
341a0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
341b0 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20  reated.)^  ^The 
341c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
341d0 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
341e0 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
341f0 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
34200 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
34210 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
34220 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
34230 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
34240 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
34250 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
34260 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
34270 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
34280 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
34290 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b  loaded.** by a [
342a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
342b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
342c0 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
342d0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
342e0 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
342f0 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
34300 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
34310 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
34320 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
34330 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
34340 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
34350 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
34360 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
34370 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
34380 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
34390 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
343a0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
343b0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
343c0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
343d0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
343e0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
343f0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
34400 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
34410 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
34420 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
34430 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
34440 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
34450 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
34460 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
34470 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
34480 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
34490 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
344a0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
344b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
344c0 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
344d0 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45   Open BLOB.** KE
344e0 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61  YWORDS: {BLOB ha
344f0 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64  ndle} {BLOB hand
34500 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  les}.**.** An in
34510 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
34520 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
34530 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e   an open BLOB on
34540 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
34550 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
34560 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
34570 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66  I/O] can be perf
34580 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63  ormed..** ^Objec
34590 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20  ts of this type 
345a0 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b  are created by [
345b0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
345c0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74  n()].** and dest
345d0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
345e0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
345f0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
34600 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
34610 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
34620 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
34630 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
34640 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
34650 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
34660 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c  ctions of the BL
34670 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  OB..** ^The [sql
34680 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
34690 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
346a0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
346b0 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74   the BLOB in byt
346c0 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
346d0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
346e0 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
346f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34700 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
34710 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
34720 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  O.**.** ^(This i
34730 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
34740 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c  a [BLOB handle |
34750 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20   handle] to the 
34760 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  BLOB located.** 
34770 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c  in row iRow, col
34780 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62  umn zColumn, tab
34790 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74  le zTable in dat
347a0 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e  abase zDb;.** in
347b0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
347c0 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74  e same BLOB that
347d0 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74   would be select
347e0 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  ed by:.**.** <pr
347f0 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54  e>.**     SELECT
34800 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44   zColumn FROM zD
34810 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b  b.zTable WHERE [
34820 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a  rowid] = iRow;.*
34830 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
34840 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 70   ^If the flags p
34850 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
34860 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42  zero, then the B
34870 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
34880 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72  r read.** and wr
34890 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20  ite access. ^If 
348a0 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
348b0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
348c0 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a  or read access..
348d0 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f  ** ^It is not po
348e0 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61  ssible to open a
348f0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
34900 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78  part of an index
34910 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20   or primary .** 
34920 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  key for writing.
34930 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65   ^If [foreign ke
34940 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61  y constraints] a
34950 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69  re enabled, it i
34960 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  s .** not possib
34970 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c  le to open a col
34980 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74  umn that is part
34990 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79   of a [child key
349a0 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a  ] for writing..*
349b0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
349c0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
349d0 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c  e is not the fil
349e0 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61  ename that conta
349f0 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ins.** the datab
34a00 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74  ase but rather t
34a10 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
34a20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
34a30 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73   that.** appears
34a40 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65   after the AS ke
34a50 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64  yword when the d
34a60 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65  atabase is conne
34a70 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41  cted using [ATTA
34a80 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  CH]..** ^For the
34a90 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
34aa0 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
34ab0 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
34ac0 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74  ..** ^For TEMP t
34ad0 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62  ables, the datab
34ae0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d  ase name is "tem
34af0 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  p"..**.** ^(On s
34b00 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
34b10 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
34b20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f  and the new [BLO
34b30 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  B handle] is wri
34b40 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c  tten.** to *ppBl
34b50 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e  ob. Otherwise an
34b60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
34b70 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70   returned and *p
34b80 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20  pBlob is set.** 
34b90 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69  to be a null poi
34ba0 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73  nter.)^.** ^This
34bb0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
34bc0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34bd0 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63  nection] error c
34be0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
34bf0 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
34c00 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
34c10 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
34c20 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
34c30 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63   related.** func
34c40 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61  tions. ^Note tha
34c50 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61  t the *ppBlob va
34c60 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73  riable is always
34c70 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20   initialized in 
34c80 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61  a.** way that ma
34c90 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69  kes it safe to i
34ca0 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62  nvoke [sqlite3_b
34cb0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20  lob_close()] on 
34cc0 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72  *ppBlob.** regar
34cd0 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
34ce0 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20  cess or failure 
34cf0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
34d00 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
34d10 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20  row that a BLOB 
34d20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f  handle points to
34d30 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20   is modified by 
34d40 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20  an.** [UPDATE], 
34d50 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20  [DELETE], or by 
34d60 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69  [ON CONFLICT] si
34d70 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68  de-effects.** th
34d80 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  en the BLOB hand
34d90 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20  le is marked as 
34da0 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68  "expired"..** Th
34db0 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e  is is true if an
34dc0 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  y column of the 
34dd0 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20  row is changed, 
34de0 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  even a column.**
34df0 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20   other than the 
34e00 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e  one the BLOB han
34e10 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29  dle is open on.)
34e20 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b  ^.** ^Calls to [
34e30 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
34e40 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
34e50 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
34e60 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64  for.** a expired
34e70 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69   BLOB handle fai
34e80 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e  l with an return
34e90 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
34ea0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68  _ABORT]..** ^(Ch
34eb0 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e  anges written in
34ec0 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20  to a BLOB prior 
34ed0 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69  to the BLOB expi
34ee0 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ring are not.** 
34ef0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74  rolled back by t
34f00 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  he expiration of
34f10 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68   the BLOB.  Such
34f20 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76   changes will ev
34f30 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d  entually.** comm
34f40 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61  it if the transa
34f50 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20  ction continues 
34f60 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e  to completion.)^
34f70 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20  .**.** ^Use the 
34f80 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
34f90 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
34fa0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
34fb0 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
34fc0 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e   opened blob.  ^
34fd0 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  The size of a bl
34fe0 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68  ob may not be ch
34ff0 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  anged by this.**
35000 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65   interface.  Use
35010 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51   the [UPDATE] SQ
35020 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61  L command to cha
35030 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  nge the size of 
35040 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a  a.** blob..**.**
35050 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
35060 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ind_zeroblob()] 
35070 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
35080 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ult_zeroblob()] 
35090 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e  interfaces.** an
350a0 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b  d the built-in [
350b0 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75  zeroblob] SQL fu
350c0 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  nction can be us
350d0 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a  ed, if desired,.
350e0 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20  ** to create an 
350f0 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c  empty, zero-fill
35100 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68  ed blob in which
35110 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
35120 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20  e using.** this 
35130 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
35140 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f   To avoid a reso
35150 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79  urce leak, every
35160 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
35170 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74  le] should event
35180 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65  ually.** be rele
35190 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  ased by a call t
351a0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
351b0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  close()]..*/.int
351c0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70   sqlite3_blob_op
351d0 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  en(.  sqlite3*,.
351e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
351f0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
35200 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74  *zTable,.  const
35210 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a   char *zColumn,.
35220 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
35230 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67  iRow,.  int flag
35240 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f  s,.  sqlite3_blo
35250 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f  b **ppBlob.);../
35260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
35270 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64  lose A BLOB Hand
35280 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73  le.**.** ^Closes
35290 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
352a0 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  andle]..**.** ^C
352b0 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68  losing a BLOB sh
352c0 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75  all cause the cu
352d0 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
352e0 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69  n to commit.** i
352f0 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f  f there are no o
35300 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70  ther BLOBs, no p
35310 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20  ending prepared 
35320 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20  statements, and 
35330 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
35340 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e  connection is in
35350 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   [autocommit mod
35360 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77  e]..** ^If any w
35370 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20  rites were made 
35380 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65  to the BLOB, the
35390 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20  y might be held 
353a0 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69  in cache.** unti
353b0 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72  l the close oper
353c0 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69  ation if they wi
353d0 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ll fit..**.** ^(
353e0 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42  Closing the BLOB
353f0 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68   often forces th
35400 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74  e changes.** out
35410 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20   to disk and so 
35420 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72  if any I/O error
35430 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69  s occur, they wi
35440 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a  ll likely occur.
35450 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ** at the time w
35460 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20  hen the BLOB is 
35470 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72  closed.  Any err
35480 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64  ors that occur d
35490 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67  uring.** closing
354a0 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73   are reported as
354b0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
354c0 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a  rn value.)^.**.*
354d0 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69 73 20  * ^(The BLOB is 
354e0 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69  closed unconditi
354f0 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66  onally.  Even if
35500 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
35510 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f  turns.** an erro
35520 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42  r code, the BLOB
35530 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64   is still closed
35540 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  .)^.**.** ^Calli
35550 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
35560 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e  with a null poin
35570 74 65 72 20 28 73 75 63 68 20 61 73 20 77 6f 75  ter (such as wou
35580 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a  ld be returned.*
35590 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20 63 61  * by a failed ca
355a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
355b0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20  lob_open()]) is 
355c0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
355d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
355e0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69  _blob_close(sqli
355f0 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
35600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
35610 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66  turn The Size Of
35620 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
35630 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74 68 65  .** ^Returns the
35640 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f   size in bytes o
35650 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73  f the BLOB acces
35660 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a  sible via the .*
35670 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  * successfully o
35680 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64  pened [BLOB hand
35690 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20  le] in its only 
356a0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a  argument.  ^The.
356b0 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62  ** incremental b
356c0 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73  lob I/O routines
356d0 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f   can only read o
356e0 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78  r overwriting ex
356f0 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63  isting.** blob c
35700 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e  ontent; they can
35710 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 73  not change the s
35720 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a  ize of a blob..*
35730 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
35740 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
35750 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
35760 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
35770 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
35780 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
35790 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
357a0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
357b0 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
357c0 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
357d0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
357e0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
357f0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
35800 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
35810 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
35820 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
35830 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
35840 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
35850 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
35860 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c  3_blob_bytes(sql
35870 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
35880 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
35890 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20  ead Data From A 
358a0 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
358b0 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ly.**.** ^(This 
358c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
358d0 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72   to read data fr
358e0 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  om an open [BLOB
358f0 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a   handle] into a.
35900 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69  ** caller-suppli
35910 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74  ed buffer. N byt
35920 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63  es of data are c
35930 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65  opied into buffe
35940 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  r Z.** from the 
35950 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74  open BLOB, start
35960 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
35970 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ffset.)^.**.** ^
35980 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
35990 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
359a0 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
359b0 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c  end of the BLOB,
359c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
359d0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
359e0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65  nd no data is re
359f0 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f  ad.  ^If N or iO
35a00 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73  ffset is.** less
35a10 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c   than zero, [SQL
35a20 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
35a30 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
35a40 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e  ta is read..** ^
35a50 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
35a60 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20  blob (and hence 
35a70 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75  the maximum valu
35a80 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a  e of N+iOffset).
35a90 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
35aa0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
35ab0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
35ac0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
35ad0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d  .**.** ^An attem
35ae0 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20  pt to read from 
35af0 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
35b00 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
35b10 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
35b20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
35b30 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ABORT]..**.** ^(
35b40 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69  On success, sqli
35b50 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20  te3_blob_read() 
35b60 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
35b70 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  K..** Otherwise,
35b80 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
35b90 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
35ba0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
35bb0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
35bc0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
35bd0 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
35be0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
35bf0 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
35c00 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
35c10 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
35c20 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
35c30 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
35c40 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
35c50 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
35c60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
35c70 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
35c80 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
35c90 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
35ca0 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
35cb0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
35cc0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
35cd0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
35ce0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
35cf0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
35d00 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ite()]..*/.int s
35d10 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
35d20 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
35d30 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c   void *Z, int N,
35d40 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
35d50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35d60 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20  Write Data Into 
35d70 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
35d80 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ally.**.** ^This
35d90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
35da0 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20  d to write data 
35db0 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  into an open [BL
35dc0 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20  OB handle] from 
35dd0 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
35de0 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e 4e 20  lied buffer. ^N 
35df0 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
35e00 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68  e copied from th
35e10 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e  e buffer Z.** in
35e20 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42  to the open BLOB
35e30 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
35e40 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
35e50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f  .** ^If the [BLO
35e60 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64  B handle] passed
35e70 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
35e80 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f  gument was not o
35e90 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69  pened for.** wri
35ea0 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20  ting (the flags 
35eb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
35ec0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
35ed0 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a  )] was zero),.**
35ee0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
35ef0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
35f00 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
35f10 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  ^This function m
35f20 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74  ay only modify t
35f30 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
35f40 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a  he BLOB; it is.*
35f50 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  * not possible t
35f60 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73  o increase the s
35f70 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73  ize of a BLOB us
35f80 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a  ing this API..**
35f90 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
35fa0 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
35fb0 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
35fc0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
35fd0 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
35fe0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
35ff0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
36000 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20  written.  ^If N 
36010 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
36020 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52  zero [SQLITE_ERR
36030 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
36040 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
36050 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ritten..** The s
36060 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ize of the BLOB 
36070 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d  (and hence the m
36080 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20  aximum value of 
36090 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61  N+iOffset).** ca
360a0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
360b0 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
360c0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
360d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
360e0 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f  * ^An attempt to
360f0 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70   write to an exp
36100 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ired [BLOB handl
36110 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  e] fails with an
36120 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  .** error code o
36130 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
36140 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20 74 68  .  ^Writes to th
36150 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75  e BLOB that occu
36160 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74  rred.** before t
36170 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  he [BLOB handle]
36180 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74   expired are not
36190 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20   rolled back by 
361a0 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f  the.** expiratio
361b0 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c  n of the handle,
361c0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
361d0 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  e those changes 
361e0 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65  might.** have be
361f0 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  en overwritten b
36200 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
36210 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65  that expired the
36220 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20   BLOB handle.** 
36230 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65  or by other inde
36240 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e  pendent statemen
36250 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  ts..**.** ^(On s
36260 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f  uccess, sqlite3_
36270 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72 65 74  blob_write() ret
36280 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
36290 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  ** Otherwise, an
362a0 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f    [error code] o
362b0 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
362c0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
362d0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
362e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
362f0 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
36300 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
36310 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
36320 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
36330 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
36340 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
36350 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
36360 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
36370 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
36380 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
36390 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
363a0 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
363b0 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
363c0 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
363d0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
363e0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
363f0 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
36400 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
36410 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
36420 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
36430 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73  te3_blob_write(s
36440 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63  qlite3_blob *, c
36450 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e  onst void *z, in
36460 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74  t n, int iOffset
36470 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36480 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65  EF: Virtual File
36490 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a   System Objects.
364a0 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20  **.** A virtual 
364b0 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29  filesystem (VFS)
364c0 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   is an [sqlite3_
364d0 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74  vfs] object.** t
364e0 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20  hat SQLite uses 
364f0 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77  to interact.** w
36500 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ith the underlyi
36510 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
36520 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74  tem.  Most SQLit
36530 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69  e builds come wi
36540 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64  th a.** single d
36550 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20  efault VFS that 
36560 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
36570 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  or the host comp
36580 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53  uter..** New VFS
36590 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  es can be regist
365a0 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e  ered and existin
365b0 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75  g VFSes can be u
365c0 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20  nregistered..** 
365d0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  The following in
365e0 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
365f0 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  vided..**.** ^Th
36600 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69  e sqlite3_vfs_fi
36610 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  nd() interface r
36620 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
36630 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20   to a VFS given 
36640 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61  its name..** ^Na
36650 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65 6e  mes are case sen
36660 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65  sitive..** ^Name
36670 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  s are zero-termi
36680 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
36690 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72  ngs..** ^If ther
366a0 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61  e is no match, a
366b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
366c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
366d0 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55  f zVfsName is NU
366e0 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  LL then the defa
366f0 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72  ult VFS is retur
36700 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20  ned..**.** ^New 
36710 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74  VFSes are regist
36720 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65  ered with sqlite
36730 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
36740 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77 20 56  ..** ^Each new V
36750 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64  FS becomes the d
36760 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68  efault VFS if th
36770 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20  e makeDflt flag 
36780 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  is set..** ^The 
36790 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20  same VFS can be 
367a0 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
367b0 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75  ple times withou
367c0 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f  t injury..** ^To
367d0 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e   make an existin
367e0 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64  g VFS into the d
367f0 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69  efault VFS, regi
36800 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a  ster it again.**
36810 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66   with the makeDf
36820 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66  lt flag set.  If
36830 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56   two different V
36840 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a  FSes with the.**
36850 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72   same name are r
36860 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62  egistered, the b
36870 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
36880 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56  ined.  If a.** V
36890 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64  FS is registered
368a0 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61   with a name tha
368b0 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  t is NULL or an 
368c0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a  empty string,.**
368d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
368e0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
368f0 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74  .**.** ^Unregist
36900 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68  er a VFS with th
36910 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  e sqlite3_vfs_un
36920 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72  register() inter
36930 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68  face..** ^(If th
36940 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
36950 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61   unregistered, a
36960 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68  nother VFS is ch
36970 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64  osen as.** the d
36980 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f  efault.  The cho
36990 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20  ice for the new 
369a0 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79  VFS is arbitrary
369b0 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76  .)^.*/.sqlite3_v
369c0 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f  fs *sqlite3_vfs_
369d0 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20  find(const char 
369e0 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20  *zVfsName);.int 
369f0 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
36a00 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
36a10 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29  *, int makeDflt)
36a20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66  ;.int sqlite3_vf
36a30 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c  s_unregister(sql
36a40 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a  ite3_vfs*);../*.
36a50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
36a60 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  exes.**.** The S
36a70 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
36a80 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  these routines f
36a90 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e  or thread.** syn
36aa0 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68  chronization. Th
36ab0 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e  ough they are in
36ac0 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72  tended for inter
36ad0 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
36ae0 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20  Lite, code that 
36af0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51  links against SQ
36b00 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69  Lite is.** permi
36b10 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20  tted to use any 
36b20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
36b30 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  s..**.** The SQL
36b40 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20  ite source code 
36b50 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c  contains multipl
36b60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
36b70 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75  s.** of these mu
36b80 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41  tex routines.  A
36b90 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d  n appropriate im
36ba0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
36bb0 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f  is selected auto
36bc0 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d  matically at com
36bd0 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68  pile-time.  ^(Th
36be0 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69  e following.** i
36bf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61  mplementations a
36c00 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  re available in 
36c10 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a  the SQLite core:
36c20 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
36c30 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
36c40 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20  EX_OS2.** <li>  
36c50 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
36c60 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20  HREAD.** <li>   
36c70 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
36c80 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
36c90 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20  E_MUTEX_NOOP.** 
36ca0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  </ul>)^.**.** ^T
36cb0 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
36cc0 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74  NOOP implementat
36cd0 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20  ion is a set of 
36ce0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74  routines.** that
36cf0 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f   does no real lo
36d00 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70  cking and is app
36d10 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
36d20 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d   in.** a single-
36d30 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
36d40 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49  tion.  ^The SQLI
36d50 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a  TE_MUTEX_OS2,.**
36d60 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
36d70 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54  HREAD, and SQLIT
36d80 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c  E_MUTEX_W32 impl
36d90 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
36da0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  re appropriate f
36db0 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20  or use on OS/2, 
36dc0 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77  Unix, and Window
36dd0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  s..**.** ^(If SQ
36de0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
36df0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
36e00 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72  _MUTEX_APPDEF pr
36e10 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61  eprocessor.** ma
36e20 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74  cro defined (wit
36e30 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45  h "-DSQLITE_MUTE
36e40 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68  X_APPDEF=1"), th
36e50 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69  en no mutex.** i
36e60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
36e70 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74   included with t
36e80 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74  he library. In t
36e90 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20  his case the.** 
36ea0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
36eb0 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d   supply a custom
36ec0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
36ed0 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a  ation using the.
36ee0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
36ef0 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20  G_MUTEX] option 
36f00 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
36f10 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e  onfig() function
36f20 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69  .** before calli
36f30 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ng sqlite3_initi
36f40 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f  alize() or any o
36f50 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69  ther public sqli
36f60 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  te3_.** function
36f70 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69   that calls sqli
36f80 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
36f90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
36fa0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
36fb0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c  oc() routine all
36fc0 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20  ocates a new.** 
36fd0 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e  mutex and return
36fe0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
36ff0 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75 72 6e  t. ^If it return
37000 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d  s NULL.** that m
37010 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65  eans that a mute
37020 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61  x could not be a
37030 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51 4c 69  llocated.  ^SQLi
37040 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e  te.** will unwin
37050 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20  d its stack and 
37060 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
37070 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74    ^(The argument
37080 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  .** to sqlite3_m
37090 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20  utex_alloc() is 
370a0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
370b0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a  eger constants:.
370c0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
370d0 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
370e0 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _FAST.** <li>  S
370f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
37100 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  RSIVE.** <li>  S
37110 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
37120 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69  IC_MASTER.** <li
37130 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
37140 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c  STATIC_MEM.** <l
37150 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
37160 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20  _STATIC_MEM2.** 
37170 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
37180 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a  EX_STATIC_PRNG.*
37190 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
371a0 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a  UTEX_STATIC_LRU.
371b0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
371c0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
371d0 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  2.** </ul>)^.**.
371e0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 77  ** ^The first tw
371f0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c  o constants (SQL
37200 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61  ITE_MUTEX_FAST a
37210 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
37220 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20 63 61  RECURSIVE).** ca
37230 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  use sqlite3_mute
37240 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65  x_alloc() to cre
37250 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74  ate.** a new mut
37260 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20 6d 75  ex.  ^The new mu
37270 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65  tex is recursive
37280 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
37290 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
372a0 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20  is used but not 
372b0 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77  necessarily so w
372c0 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
372d0 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 0a 2a  _FAST is used..*
372e0 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c  * The mutex impl
372f0 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
37300 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65  not need to make
37310 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a   a distinction.*
37320 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
37330 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
37340 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
37350 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65  X_FAST if it doe
37360 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f  s.** not want to
37370 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
37380 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20 72  only request a r
37390 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20 69  ecursive mutex i
373a0 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65  n.** cases where
373b0 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73   it really needs
373c0 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66 61 73   one.  ^If a fas
373d0 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76  ter non-recursiv
373e0 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  e mutex.** imple
373f0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61  mentation is ava
37400 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f  ilable on the ho
37410 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65  st platform, the
37420 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d   mutex subsystem
37430 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e  .** might return
37440 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e   such a mutex in
37450 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c   response to SQL
37460 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a  ITE_MUTEX_FAST..
37470 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72  **.** ^The other
37480 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74   allowed paramet
37490 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  ers to sqlite3_m
374a0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e  utex_alloc() (an
374b0 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20  ything other.** 
374c0 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  than SQLITE_MUTE
374d0 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54  X_FAST and SQLIT
374e0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
374f0 45 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a  E) each return.*
37500 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
37510 20 73 74 61 74 69 63 20 70 72 65 65 78 69 73 74   static preexist
37520 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53 69 78  ing mutex.  ^Six
37530 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   static mutexes 
37540 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74  are.** used by t
37550 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69  he current versi
37560 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46  on of SQLite.  F
37570 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
37580 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20  f SQLite.** may 
37590 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  add additional s
375a0 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20  tatic mutexes.  
375b0 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61  Static mutexes a
375c0 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a  re for internal.
375d0 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65  ** use by SQLite
375e0 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
375f0 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51  ions that use SQ
37600 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f  Lite mutexes sho
37610 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20  uld.** use only 
37620 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
37630 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  xes returned by 
37640 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
37650 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  T or.** SQLITE_M
37660 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a  UTEX_RECURSIVE..
37670 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
37680 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64   if one of the d
37690 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72  ynamic mutex par
376a0 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f  ameters (SQLITE_
376b0 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72  MUTEX_FAST.** or
376c0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
376d0 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64  CURSIVE) is used
376e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75   then sqlite3_mu
376f0 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72  tex_alloc().** r
37700 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65  eturns a differe
37710 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72  nt mutex on ever
37720 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f  y call.  ^But fo
37730 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20  r the static.** 
37740 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65  mutex types, the
37750 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72   same mutex is r
37760 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79  eturned on every
37770 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a   call that has.*
37780 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20  * the same type 
37790 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
377a0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
377b0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
377c0 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72  deallocates a pr
377d0 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f  eviously.** allo
377e0 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75  cated dynamic mu
377f0 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20 69 73  tex.  ^SQLite is
37800 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c   careful to deal
37810 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20  locate every.** 
37820 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68  dynamic mutex th
37830 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e  at it allocates.
37840 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75    The dynamic mu
37850 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62  texes must not b
37860 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e  e in.** use when
37870 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f   they are deallo
37880 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70 74 69  cated.  Attempti
37890 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65  ng to deallocate
378a0 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74   a static.** mut
378b0 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ex results in un
378c0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
378d0 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76 65 72  .  ^SQLite never
378e0 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20   deallocates.** 
378f0 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  a static mutex..
37900 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37910 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
37920 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
37930 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65  ex_try() routine
37940 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20  s attempt.** to 
37950 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20  enter a mutex.  
37960 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65  ^If another thre
37970 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69  ad is already wi
37980 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a  thin the mutex,.
37990 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
379a0 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c  _enter() will bl
379b0 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ock and sqlite3_
379c0 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c  mutex_try() will
379d0 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
379e0 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20 73 71  E_BUSY.  ^The sq
379f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
37a00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
37a10 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a  rns [SQLITE_OK].
37a20 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66  ** upon successf
37a30 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74  ul entry.  ^(Mut
37a40 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69  exes created usi
37a50 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  ng.** SQLITE_MUT
37a60 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e  EX_RECURSIVE can
37a70 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74   be entered mult
37a80 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68  iple times by th
37a90 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a  e same thread..*
37aa0 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20  * In such cases 
37ab0 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75  the,.** mutex mu
37ac0 73 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20  st be exited an 
37ad0 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  equal number of 
37ae0 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f  times before ano
37af0 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63  ther thread.** c
37b00 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49  an enter.)^  ^(I
37b10 66 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  f the same threa
37b20 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72  d tries to enter
37b30 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69   any other.** ki
37b40 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65  nd of mutex more
37b50 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20   than once, the 
37b60 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
37b70 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65  fined..** SQLite
37b80 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69   will never exhi
37b90 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61  bit.** such beha
37ba0 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20  vior in its own 
37bb0 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 29  use of mutexes.)
37bc0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73  ^.**.** ^(Some s
37bd0 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d  ystems (for exam
37be0 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29  ple, Windows 95)
37bf0 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
37c00 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
37c10 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
37c20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
37c30 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73  y().  On those s
37c40 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f  ystems, sqlite3_
37c50 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77  mutex_try().** w
37c60 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
37c70 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20  n SQLITE_BUSY.  
37c80 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
37c90 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a  only ever uses.*
37ca0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
37cb0 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69  try() as an opti
37cc0 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73  mization so this
37cd0 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62   is acceptable b
37ce0 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a  ehavior.)^.**.**
37cf0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75   ^The sqlite3_mu
37d00 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74  tex_leave() rout
37d10 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 65  ine exits a mute
37d20 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72  x that was.** pr
37d30 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64  eviously entered
37d40 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72   by the same thr
37d50 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62 65 68  ead.   ^(The beh
37d60 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
37d70 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74  fined if the mut
37d80 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  ex is not curren
37d90 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74  tly entered by t
37da0 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68  he.** calling th
37db0 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63  read or is not c
37dc0 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74  urrently allocat
37dd0 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  ed.  SQLite will
37de0 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74  .** never do eit
37df0 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  her.)^.**.** ^If
37e00 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
37e10 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
37e20 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f  nter(), sqlite3_
37e30 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a  mutex_try(), or.
37e40 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
37e50 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55  _leave() is a NU
37e60 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
37e70 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69   all three routi
37e80 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73  nes.** behave as
37e90 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53   no-ops..**.** S
37ea0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
37eb0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20  3_mutex_held()] 
37ec0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  and [sqlite3_mut
37ed0 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a  ex_notheld()]..*
37ee0 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  /.sqlite3_mutex 
37ef0 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  *sqlite3_mutex_a
37f00 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
37f10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
37f20 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ee(sqlite3_mutex
37f30 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
37f40 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c  _mutex_enter(sql
37f50 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e  ite3_mutex*);.in
37f60 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
37f70 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  try(sqlite3_mute
37f80 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  x*);.void sqlite
37f90 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71  3_mutex_leave(sq
37fa0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a  lite3_mutex*);..
37fb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37fc0 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62  Mutex Methods Ob
37fd0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
37fe0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
37ff0 74 72 75 63 74 75 72 65 20 64 65 66 69 6e 65 73  tructure defines
38000 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72   the low-level r
38010 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20  outines.** used 
38020 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20  to allocate and 
38030 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a  use mutexes..**.
38040 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20  ** Usually, the 
38050 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d  default mutex im
38060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72  plementations pr
38070 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 74 65  ovided by SQLite
38080 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65   are.** sufficie
38090 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  nt, however the 
380a0 75 73 65 72 20 68 61 73 20 74 68 65 20 6f 70 74  user has the opt
380b0 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74  ion of substitut
380c0 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20  ing a custom.** 
380d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
380e0 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64  or specialized d
380f0 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79  eployments or sy
38100 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20  stems for which 
38110 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e  SQLite.** does n
38120 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 75 69  ot provide a sui
38130 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
38140 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61  tion. In this ca
38150 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20  se, the user.** 
38160 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75  creates and popu
38170 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63  lates an instanc
38180 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
38190 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74  ure to pass.** t
381a0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
381b0 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68  () along with th
381c0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
381d0 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a  _MUTEX] option..
381e0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  ** Additionally,
381f0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
38200 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  this structure c
38210 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61 6e  an be used as an
38220 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61  .** output varia
38230 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e  ble when queryin
38240 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72  g the system for
38250 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74   the current mut
38260 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
38270 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20  tion, using the 
38280 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
38290 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e  ETMUTEX] option.
382a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74  .**.** ^The xMut
382b0 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65  exInit method de
382c0 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
382d0 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
382e0 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
382f0 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69   system initiali
38300 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71  zation by the sq
38310 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
38320 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  () function..** 
38330 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20  ^The xMutexInit 
38340 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
38350 20 62 79 20 53 51 4c 69 74 65 20 65 78 61 63 74   by SQLite exact
38360 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ly once for each
38370 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20 63 61  .** effective ca
38380 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69  ll to [sqlite3_i
38390 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  nitialize()]..**
383a0 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 45  .** ^The xMutexE
383b0 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65  nd method define
383c0 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  d by this struct
383d0 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ure is invoked a
383e0 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73  s.** part of sys
383f0 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20  tem shutdown by 
38400 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  the sqlite3_shut
38410 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e  down() function.
38420 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   The.** implemen
38430 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d  tation of this m
38440 65 74 68 6f 64 20 69 73 20 65 78 70 65 63 74 65  ethod is expecte
38450 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c  d to release all
38460 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20   outstanding.** 
38470 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e  resources obtain
38480 65 64 20 62 79 20 74 68 65 20 6d 75 74 65 78 20  ed by the mutex 
38490 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e  methods implemen
384a0 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c  tation, especial
384b0 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61  ly.** those obta
384c0 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d 75 74  ined by the xMut
384d0 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 20  exInit method.  
384e0 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29  ^The xMutexEnd()
384f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
38500 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79   invoked exactly
38510 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63   once for each c
38520 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
38530 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a  shutdown()]..**.
38540 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69 6e 69  ** ^(The remaini
38550 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73  ng seven methods
38560 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73   defined by this
38570 20 73 74 72 75 63 74 75 72 65 20 28 78 4d 75 74   structure (xMut
38580 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74  exAlloc,.** xMut
38590 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e  exFree, xMutexEn
385a0 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20  ter, xMutexTry, 
385b0 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75  xMutexLeave, xMu
385c0 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78  texHeld and.** x
385d0 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d  MutexNotheld) im
385e0 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c  plement the foll
385f0 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
38600 20 28 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a   (respectively):
38610 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
38620 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
38630 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c  mutex_alloc()] <
38640 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
38650 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66  [sqlite3_mutex_f
38660 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  ree()] </li>.** 
38670 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
38680 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20  _mutex_enter()] 
38690 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
386a0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
386b0 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  try()] </li>.** 
386c0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
386d0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20  _mutex_leave()] 
386e0 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
386f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
38700 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  held()] </li>.**
38710 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
38720 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
38730 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  )] </li>.** </ul
38740 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e  >)^.**.** The on
38750 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ly difference is
38760 20 74 68 61 74 20 74 68 65 20 70 75 62 6c 69 63   that the public
38770 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e   sqlite3_XXX fun
38780 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65  ctions enumerate
38790 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e  d.** above silen
387a0 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69  tly ignore any i
387b0 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20  nvocations that 
387c0 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  pass a NULL poin
387d0 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ter instead.** o
387e0 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20  f a valid mutex 
387f0 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c  handle. The impl
38800 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
38810 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e  he methods defin
38820 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74  ed.** by this st
38830 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20  ructure are not 
38840 72 65 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64  required to hand
38850 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20 74 68  le this case, th
38860 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20  e results.** of 
38870 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  passing a NULL p
38880 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
38890 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20  f a valid mutex 
388a0 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66  handle are undef
388b0 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74  ined.** (i.e. it
388c0 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 74   is acceptable t
388d0 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70  o provide an imp
388e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation t