/ Hex Artifact Content
Login

Artifact b82b926ef9c10ca12373c2ecc8bbd2f5a9aad1dc:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5630: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5640: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5650: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70  * The xDeviceCap
5660: 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64  abilities method
5670: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
5680: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5690: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
56a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
56b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
56c0: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
56d0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
56e0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
56f0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5700: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5710: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5720: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5730: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5740: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5750: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
5760: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5770: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
5780: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
5790: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
57a0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
57b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57c0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
57d0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
57e0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
57f0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5800: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5810: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5820: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5830: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5840: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5850: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5860: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5870: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5880: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5890: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
58a0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
58b0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
58c0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
58d0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
58e0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
58f0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5900: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5910: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5920: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5930: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5940: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5950: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5960: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5970: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5980: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5990: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
59a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
59b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
59c0: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
59d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59e0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
59f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5a00: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5a10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5a20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5a30: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5a40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5a50: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5a60: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5a70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5a80: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5a90: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5aa0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5ab0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ac0: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5ad0: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5ae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5af0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5b00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5b10: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5b20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5b30: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
5b40: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5b50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5b60: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5b70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5b80: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5b90: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5ba0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
5bb0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5bc0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5bd0: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
5be0: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c00: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
5c10: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
5c20: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000800../*.** C
5c30: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5c40: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
5c50: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5c60: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5c70: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5c80: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5c90: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5ca0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5cb0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5cc0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5cd0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5ce0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5cf0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5d00: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5d10: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5d20: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5d30: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5d50: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d70: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5d80: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5d90: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5da0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5db0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
5dc0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
5dd0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
5de0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
5df0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
5e00: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
5e10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
5e20: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
5e30: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
5e40: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
5e50: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
5e60: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
5e70: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
5e80: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
5e90: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
5ea0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
5eb0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
5ec0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
5ed0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
5ee0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
5ef0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
5f00: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
5f10: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
5f20: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
5f30: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
5f40: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
5f50: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
5f60: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
5f70: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
5f80: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
5f90: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
5fa0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
5fb0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
5fc0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
5fd0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
5fe0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
5ff0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65   fsync()..*/.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6010: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
6020: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
6030: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6040: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
6050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6060: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
6070: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
6080: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6090: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
60a0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
60b0: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
60c0: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
60d0: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
60e0: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
60f0: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
6100: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
6110: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
6120: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
6130: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
6140: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
6150: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
6160: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
6170: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
6180: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
6190: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
61a0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
61b0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
61c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
61d0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
61e0: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
61f0: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
6200: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
6210: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
6220: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
6230: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
6240: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
6250: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
6260: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
6270: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
6280: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
6290: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
62a0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
62b0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
62c0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
62d0: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
62e0: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
62f0: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
6300: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
6310: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f  [sqlite3_vfs] xO
6320: 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  pen method popul
6330: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
6340: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6350: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
6360: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
6370: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
6380: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
6390: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
63a0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
63b0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
63c0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
63d0: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
63e0: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
63f0: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
6400: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
6410: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
6420: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
6430: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6440: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
6450: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
6460: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
6470: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6480: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
6490: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
64a0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
64b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
64c0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
64d0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
64e0: 65 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65  even if the xOpe
64f0: 6e 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  n reported that 
6500: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
6510: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
6520: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
6530: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
6540: 67 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e  g a failed xOpen
6550: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78  .** is for the x
6560: 4f 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20  Open to set the 
6570: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
6580: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f  thods element to
6590: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
65a0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
65b0: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
65c0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
65d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
65e0: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
65f0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
6600: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
6610: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
6620: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
6630: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
6640: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6650: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
6660: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
6670: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
6680: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
6690: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
66a0: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
66b0: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
66c0: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
66d0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
66e0: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
66f0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
6700: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
6710: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
6720: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6730: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
6740: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
6750: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
6760: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
6770: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
6780: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
6790: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
67a0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
67b0: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
67c0: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
67d0: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
67e0: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
67f0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6800: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
6810: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
6820: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
6830: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
6840: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
6850: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
6860: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
6870: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
6880: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
6890: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
68a0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
68b0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
68c0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
68d0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
68e0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
68f0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
6900: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
6910: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
6920: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
6930: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
6940: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
6950: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
6960: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
6970: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
6980: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
6990: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
69a0: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
69b0: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
69c0: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
69d0: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
69e0: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
69f0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
6a00: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
6a10: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
6a20: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
6a30: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
6a40: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
6a50: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
6a60: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
6a70: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
6a80: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
6a90: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
6aa0: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
6ab0: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
6ac0: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
6ad0: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
6ae0: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
6af0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
6b00: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
6b10: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
6b20: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
6b30: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
6b40: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
6b50: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
6b60: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
6b70: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
6b80: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
6b90: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
6ba0: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
6bb0: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
6bc0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
6bd0: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
6be0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
6bf0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
6c00: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
6c10: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
6c20: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
6c30: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
6c40: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
6c50: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
6c60: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a  oid conflicts..*
6c70: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
6c80: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
6c90: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
6ca0: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
6cb0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
6cc0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
6cd0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
6ce0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
6cf0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
6d00: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
6d10: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
6d20: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
6d30: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
6d40: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6d50: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
6d60: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
6d70: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
6d80: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
6d90: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
6da0: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
6db0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6dc0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6dd0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
6de0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6df0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
6e00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6e10: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
6e20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6e30: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
6e40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6e50: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
6e60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6e70: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
6e80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6e90: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
6ea0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6eb0: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
6ec0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6ed0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
6ee0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ef0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
6f00: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
6f20: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
6f30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6f40: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6f50: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6f60: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6f70: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6f80: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f90: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
6fa0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6fb0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6fc0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
6fd0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
6fe0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
6ff0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
7000: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
7010: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
7020: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
7030: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7040: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
7050: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
7060: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
7070: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
7080: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
7090: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
70a0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
70b0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
70c0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
70d0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
70e0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
70f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7100: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
7110: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
7120: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
7130: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
7140: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
7150: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
7160: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
7170: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
7180: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
7190: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
71a0: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
71b0: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
71c0: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
71d0: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
71e0: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
71f0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
7200: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
7210: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
7220: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
7230: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
7240: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
7250: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
7260: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
7270: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
7280: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7290: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
72a0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72b0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
72c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
72d0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
72e0: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
72f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7300: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
7310: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
7320: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
7330: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
7340: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
7350: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
7360: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
7370: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
7380: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
7390: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
73a0: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
73b0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
73c0: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
73d0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
73e0: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
73f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7400: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
7410: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
7420: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
7430: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
7440: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
7450: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
7460: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7470: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
7480: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7490: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
74a0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
74b0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
74c0: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
74d0: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
74e0: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
74f0: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
7500: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7510: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
7520: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
7530: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7540: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7550: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7560: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69  version 1 */.  i
7570: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71  nt (*xShmMap)(sq
7580: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7590: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20   iPg, int pgsz, 
75a0: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69  int, void volati
75b0: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  le**);.  int (*x
75c0: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  ShmLock)(sqlite3
75d0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73  _file*, int offs
75e0: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66  et, int n, int f
75f0: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a  lags);.  void (*
7600: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c  xShmBarrier)(sql
7610: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7620: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28  nt (*xShmUnmap)(
7630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7640: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a  nt deleteFlag);.
7650: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
7660: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
7670: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20   version 2 */.  
7680: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
7690: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
76a0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
76b0: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
76c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
76d0: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
76e0: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a  ol Opcodes.**.**
76f0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
7700: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
7710: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
7720: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7730: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
7740: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7750: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
7760: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7770: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
7780: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
7790: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
77a0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
77b0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
77c0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
77d0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
77e0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
77f0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
7800: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
7810: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
7820: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
7830: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
7840: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7850: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
7860: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
7870: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7880: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
7890: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
78a0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
78b0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
78c0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
78d0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
78e0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
78f0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
7900: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
7910: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
7920: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
7930: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
7940: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
7950: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
7960: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  INT] opcode is u
7970: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f  sed by SQLite to
7980: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a   give the VFS.**
7990: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66   layer a hint of
79a0: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64   how large the d
79b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
79c0: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72  l grow to be dur
79d0: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  ing the.** curre
79e0: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  nt transaction. 
79f0: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
7a00: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  t guaranteed to 
7a10: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20  be accurate but 
7a20: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63  it.** is often c
7a30: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72  lose.  The under
7a40: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20  lying VFS might 
7a50: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c  choose to preall
7a60: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a  ocate database.*
7a70: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73  * file space bas
7a80: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ed on this hint 
7a90: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70  in order to help
7aa0: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
7ab0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
7ac0: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2f 0a 23  run faster..*/.#
7ad0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
7ae0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
7af0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
7b00: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
7b10: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
7b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
7b30: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
7b40: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
7b50: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
7b60: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
7b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
7b80: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
7b90: 20 20 20 20 20 35 0a 0a 2f 2a 0a 2a 2a 20 43 41       5../*.** CA
7ba0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
7bb0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
7bc0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
7bd0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
7be0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
7bf0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
7c00: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
7c10: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
7c20: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
7c30: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
7c40: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
7c50: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
7c60: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
7c70: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
7c80: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
7c90: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
7ca0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
7cb0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
7cc0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
7cd0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
7ce0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
7cf0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7d00: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
7d10: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
7d20: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7d30: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
7d40: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
7d50: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
7d60: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
7d70: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
7d80: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
7d90: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
7da0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
7db0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
7dc0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
7dd0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
7de0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
7df0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
7e00: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a  file system"..**
7e10: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
7e20: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
7e30: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
7e40: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
7e50: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
7e60: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
7e70: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
7e80: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
7e90: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
7ea0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
7eb0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
7ec0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
7ed0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
7ee0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
7ef0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
7f00: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
7f10: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
7f20: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
7f30: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
7f40: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
7f50: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
7f60: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
7f70: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
7f80: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
7f90: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
7fa0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
7fb0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
7fc0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
7fd0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
7fe0: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
7ff0: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
8000: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
8010: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
8020: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
8030: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
8040: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
8050: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
8060: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
8070: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
8080: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
8090: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
80a0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
80b0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
80c0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
80d0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
80e0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
80f0: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
8100: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
8110: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
8120: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
8130: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
8140: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
8150: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
8160: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
8170: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
8180: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
8190: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
81a0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
81b0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
81c0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
81d0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
81e0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
81f0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
8200: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
8210: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
8220: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
8230: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
8240: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
8250: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
8260: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
8270: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
8280: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
8290: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
82a0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
82b0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
82c0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
82d0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
82e0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
82f0: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
8300: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
8310: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
8320: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
8330: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61   SQLite will gua
8340: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20  rantee that the 
8350: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
8360: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
8370: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
8380: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
8390: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
83a0: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
83b0: 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72  e().  SQLite fur
83c0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
83d0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
83e0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
83f0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
8400: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
8410: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
8420: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
8430: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
8440: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8450: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
8460: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
8470: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
8480: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
8490: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
84a0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
84b0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
84c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
84d0: 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69  meter is xOpen i
84e0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
84f0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
8500: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
8510: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
8520: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
8530: 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a   Whenever the .*
8540: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
8550: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
8560: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
8570: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
8580: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
8590: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
85a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
85b0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
85c0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
85d0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
85e0: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
85f0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
8600: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
8610: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
8620: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
8630: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
8640: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
8650: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
8660: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
8670: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
8680: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
8690: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
86a0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
86b0: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
86c0: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
86d0: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
86e0: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
86f0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
8700: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
8710: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
8720: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
8730: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
8740: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  * SQLite will al
8750: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
8760: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
8770: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
8780: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
8790: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
87a0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
87b0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
87c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
87d0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
87e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
87f0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
8800: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8810: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
8820: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8830: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
8840: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8850: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
8860: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8870: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
8880: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
8890: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
88a0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
88b0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
88c0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
88d0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
88e0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
88f0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
8900: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
8910: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
8920: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
8930: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
8940: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
8950: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
8960: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
8970: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
8980: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
8990: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
89a0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
89b0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
89c0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
89d0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
89e0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
89f0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
8a00: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
8a10: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
8a20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8a30: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
8a40: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
8a50: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
8a60: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
8a70: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
8a80: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
8a90: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
8aa0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
8ab0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
8ac0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
8ad0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
8ae0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
8af0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
8b00: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
8b10: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
8b20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8b30: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8b40: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
8b50: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
8b60: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
8b70: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8b80: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8b90: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
8ba0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
8bb0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
8bc0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
8bd0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
8be0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8bf0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
8c00: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61  for TEMP  databa
8c10: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e  ses, journals an
8c20: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c  d for subjournal
8c30: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  s..**.** The [SQ
8c40: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
8c50: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
8c60: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
8c70: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
8c80: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
8c90: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
8ca0: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
8cb0: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
8cc0: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
8cd0: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
8ce0: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
8cf0: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
8d00: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
8d10: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
8d20: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
8d30: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
8d40: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
8d50: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
8d60: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
8d70: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
8d80: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
8d90: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
8da0: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
8db0: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
8dc0: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
8dd0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
8de0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
8df0: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
8e00: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
8e10: 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20 73  **.** At least s
8e20: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
8e30: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
8e40: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
8e50: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
8e60: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
8e70: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
8e80: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
8e90: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
8ea0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
8eb0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
8ec0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
8ed0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
8ee0: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
8ef0: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
8f00: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
8f10: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
8f20: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
8f30: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
8f40: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
8f50: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
8f60: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
8f70: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
8f80: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
8f90: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
8fa0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
8fb0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
8fc0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
8fd0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
8fe0: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
8ff0: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
9000: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
9010: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
9020: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
9030: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
9040: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
9050: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
9060: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
9070: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
9080: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
9090: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
90a0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
90b0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
90c0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
90d0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
90e0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
90f0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
9100: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
9110: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
9120: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
9130: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
9140: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
9150: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
9160: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  ectory..**.** SQ
9170: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
9180: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
9190: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
91a0: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
91b0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
91c0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
91d0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
91e0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
91f0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
9200: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
9210: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
9220: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
9230: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
9240: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
9250: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
9260: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
9270: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
9280: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
9290: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
92a0: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
92b0: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
92c0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
92d0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
92e0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
92f0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
9300: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
9310: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
9320: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
9330: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
9340: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
9350: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
9360: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
9370: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
9380: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
9390: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
93a0: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
93b0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
93c0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
93d0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
93e0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
93f0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
9400: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
9410: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
9420: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
9430: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
9440: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
9450: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
9460: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
9470: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
9480: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
9490: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
94a0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
94b0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
94c0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
94d0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
94e0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
94f0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65  onds given.  The
9500: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
9510: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
9520: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
9530: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
9540: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
9550: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
9560: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
9570: 2e 0a 2a 2a 20 54 68 65 20 78 43 75 72 72 65 6e  ..** The xCurren
9580: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
9590: 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20  hod returns, as 
95a0: 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20  an integer, the 
95b0: 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75  Julian.** Day Nu
95c0: 6d 62 65 72 20 6d 75 6c 74 69 70 6c 65 64 20 62  mber multipled b
95d0: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
95e0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
95f0: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
9600: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
9610: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
9620: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
9630: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
9640: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
9650: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
9660: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
9670: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
9680: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
9690: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
96a0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
96b0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
96c0: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
96d0: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
96e0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
96f0: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
9700: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
9710: 61 69 6c 61 62 6c 65 2e 0a 2a 2f 0a 74 79 70 65  ailable..*/.type
9720: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
9730: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
9740: 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  fs;.struct sqlit
9750: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
9760: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
9770: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
9780: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
9790: 28 63 75 72 72 65 6e 74 6c 79 20 32 29 20 2a 2f  (currently 2) */
97a0: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
97b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
97c0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
97d0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
97e0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
97f0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
9800: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
9810: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
9820: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
9830: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
9840: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
9850: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
9860: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
9870: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
9880: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
9890: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
98a0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
98b0: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
98c0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
98d0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
98e0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
98f0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9900: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
9910: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
9920: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
9930: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
9940: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
9950: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
9960: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9970: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
9980: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
9990: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
99a0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
99b0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
99c0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
99d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
99e0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
99f0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
9a00: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
9a10: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
9a20: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
9a30: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
9a40: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9a50: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
9a60: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
9a70: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
9a80: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
9a90: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
9aa0: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
9ab0: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
9ac0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
9ad0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
9ae0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
9af0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
9b00: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
9b10: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
9b20: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
9b30: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
9b40: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
9b50: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
9b60: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
9b70: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
9b80: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
9b90: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
9ba0: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
9bb0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
9bc0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
9bd0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
9be0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
9bf0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
9c00: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
9c10: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
9c20: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
9c30: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
9c40: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
9c50: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
9c60: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
9c70: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
9c80: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
9c90: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
9ca0: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
9cb0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
9cc0: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
9cd0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
9ce0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
9cf0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
9d00: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
9d10: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
9d20: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
9d30: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
9d40: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
9d50: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
9d60: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
9d70: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
9d80: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
9d90: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
9da0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
9db0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
9dc0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
9dd0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
9de0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
9df0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
9e00: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
9e10: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
9e20: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
9e30: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
9e40: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
9e50: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
9e60: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
9e70: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
9e80: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
9e90: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
9ea0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
9eb0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
9ec0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9ed0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
9ee0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
9ef0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
9f00: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
9f10: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
9f20: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
9f30: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
9f40: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
9f50: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
9f60: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
9f70: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
9f80: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
9f90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
9fa0: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
9fb0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
9fc0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
9fd0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
9fe0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
9ff0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
a000: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
a010: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
a020: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
a030: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
a040: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
a050: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
a060: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
a070: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
a080: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
a090: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
a0a0: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
a0b0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
a0c0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
a0d0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
a0e0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
a0f0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
a100: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
a110: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
a120: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
a130: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
a140: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
a150: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
a160: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
a170: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
a180: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
a190: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
a1a0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
a1b0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
a1c0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
a1d0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
a1e0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
a1f0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
a200: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
a210: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
a220: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
a230: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
a240: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
a250: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
a260: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
a270: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
a280: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
a290: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
a2a0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
a2b0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
a2c0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
a2d0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
a2e0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
a2f0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
a300: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
a310: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
a320: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
a330: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
a340: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
a350: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
a360: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
a370: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
a380: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
a390: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
a3a0: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
a3b0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
a3c0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74  * was given no t
a3d0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
a3e0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
a3f0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
a400: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
a410: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
a420: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
a430: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
a440: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
a450: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
a460: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
a470: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
a480: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
a490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
a4a0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
a4b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
a4c0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
a4d0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
a4e0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
a4f0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
a500: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
a510: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
a520: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
a530: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
a540: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
a550: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
a560: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
a570: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
a580: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
a590: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
a5a0: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
a5b0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
a5c0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
a5d0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
a5e0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
a5f0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
a600: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
a610: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
a620: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
a630: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
a640: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
a650: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
a660: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
a670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
a680: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
a690: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
a6a0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
a6b0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
a6c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
a6d0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
a6e0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
a6f0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
a700: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
a710: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a720: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
a730: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
a740: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
a750: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
a760: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
a770: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
a780: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
a790: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
a7a0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
a7b0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
a7c0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
a7d0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
a7e0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
a7f0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
a800: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
a810: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
a820: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
a830: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
a840: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a850: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
a860: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
a870: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
a880: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
a890: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
a8a0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
a8b0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
a8c0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
a8d0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
a8e0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
a8f0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
a900: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
a910: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a920: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
a930: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
a940: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
a950: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
a960: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
a970: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
a980: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
a990: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
a9a0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
a9b0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
a9c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a9d0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
a9e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a9f0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
aa00: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
aa10: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
aa20: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
aa30: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
aa40: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
aa50: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
aa60: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
aa70: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
aa80: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
aa90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
aaa0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
aab0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
aac0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
aad0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
aae0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
aaf0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
ab00: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
ab10: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
ab20: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
ab30: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
ab40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ab50: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
ab60: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
ab70: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
ab80: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
ab90: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
aba0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
abb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
abc0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
abd0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
abe0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
abf0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
ac00: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
ac10: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
ac20: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
ac30: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
ac40: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
ac50: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
ac60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ac70: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
ac80: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
ac90: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
aca0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
acb0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
acc0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
acd0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
ace0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
acf0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
ad00: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
ad10: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
ad20: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
ad30: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
ad40: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
ad50: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
ad60: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
ad70: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ad80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ad90: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
ada0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
adb0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
adc0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
add0: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
ade0: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
adf0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
ae00: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
ae10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
ae20: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
ae30: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
ae40: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
ae50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ae60: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
ae70: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
ae80: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
ae90: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
aea0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
aeb0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
aec0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
aed0: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
aee0: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
aef0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
af00: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
af10: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
af20: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
af30: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
af40: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
af50: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
af60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
af70: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
af80: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
af90: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
afa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
afb0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
afc0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
afd0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
afe0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
aff0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
b000: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
b010: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
b020: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
b030: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
b040: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
b050: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
b060: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
b070: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
b080: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
b090: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
b0a0: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
b0b0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
b0c0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
b0d0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
b0e0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
b0f0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
b100: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
b110: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
b120: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
b130: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
b140: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
b150: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
b160: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
b170: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
b180: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
b190: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
b1a0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
b1b0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
b1c0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
b1d0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
b1e0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
b1f0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
b200: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
b210: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
b220: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
b230: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
b240: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
b250: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
b260: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
b270: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
b280: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
b290: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
b2a0: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
b2b0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
b2c0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
b2d0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
b2e0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
b2f0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
b300: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
b310: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
b320: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
b330: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
b340: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
b350: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
b360: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
b370: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
b380: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
b390: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
b3a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
b3b0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
b3c0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
b3d0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
b3e0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
b3f0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
b400: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
b410: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
b420: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
b430: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
b440: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b450: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
b460: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
b470: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
b480: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
b490: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
b4a0: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
b4b0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
b4c0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
b4d0: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
b4e0: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
b4f0: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
b500: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
b510: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
b520: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
b530: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
b540: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
b550: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
b560: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
b570: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
b580: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
b590: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
b5a0: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
b5b0: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
b5c0: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
b5d0: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
b5e0: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
b5f0: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
b600: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
b610: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
b620: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
b630: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
b640: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
b650: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
b660: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
b670: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
b680: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
b690: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
b6a0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
b6b0: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
b6c0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
b6d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
b6e0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
b6f0: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
b700: 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
b710: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
b720: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
b730: 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
b740: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
b750: 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
b760: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
b770: 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
b780: 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
b790: 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
b7a0: 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
b7b0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
b7c0: 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
b7d0: 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
b7e0: 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
b7f0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
b800: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
b810: 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
b820: 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
b830: 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
b840: 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
b850: 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
b860: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
b870: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
b880: 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
b890: 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
b8a0: 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
b8b0: 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
b8c0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
b8d0: 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
b8e0: 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
b8f0: 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
b900: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
b910: 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
b920: 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
b930: 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
b940: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
b950: 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
b960: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
b970: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
b980: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
b990: 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
b9a0: 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
b9b0: 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
b9c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
b9d0: 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
b9e0: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
b9f0: 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
ba00: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
ba10: 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
ba20: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
ba30: 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
ba40: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
ba50: 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
ba60: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
ba70: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
ba80: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
ba90: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
baa0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
bab0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
bac0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
bad0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
bae0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
baf0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
bb00: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
bb10: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
bb20: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
bb30: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
bb40: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
bb50: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
bb60: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
bb70: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
bb80: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
bb90: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
bba0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
bbb0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
bbc0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
bbd0: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
bbe0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
bbf0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
bc00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
bc10: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
bc20: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
bc30: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
bc40: 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
bc50: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
bc60: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
bc70: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
bc80: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
bc90: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
bca0: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
bcb0: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
bcc0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
bcd0: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
bce0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
bcf0: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
bd00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
bd10: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
bd20: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
bd30: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
bd40: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
bd50: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
bd60: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
bd70: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
bd80: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
bd90: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
bda0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
bdb0: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
bdc0: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
bdd0: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
bde0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
bdf0: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
be00: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
be10: 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  t).  The.** sqli
be20: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
be30: 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64  interface should
be40: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d   only be used im
be50: 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a  mediately after.
be60: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
be70: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72  connection is cr
be80: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
be90: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a  ite3_open()],.**
bea0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
beb0: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
bec0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a  _open_v2()].  .*
bed0: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
bee0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
bef0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
bf00: 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
bf10: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
bf20: 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65  verb - an intege
bf30: 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69  r code that indi
bf40: 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73  cates what.** as
bf50: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
bf60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bf70: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
bf80: 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e  gured..** The on
bf90: 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68  ly choice for th
bfa0: 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c  is value is [SQL
bfb0: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
bfc0: 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20  KASIDE]..** New 
bfd0: 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79  verbs are likely
bfe0: 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20   to be added in 
bff0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
c000: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64  of SQLite..** Ad
c010: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
c020: 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65  ts depend on the
c030: 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
c040: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
c050: 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
c060: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
c070: 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
c080: 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
c090: 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
c0a0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
c0b0: 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
c0c0: 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
c0d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
c0e0: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
c0f0: 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
c100: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
c110: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
c120: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
c130: 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
c140: 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
c150: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
c160: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
c170: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
c180: 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
c190: 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
c1a0: 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
c1b0: 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
c1c0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
c1d0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
c1e0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
c1f0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
c200: 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
c210: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
c220: 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
c230: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
c240: 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
c250: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
c260: 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
c270: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
c280: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
c290: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
c2a0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
c2b0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
c2c0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
c2d0: 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
c2e0: 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
c2f0: 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
c300: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
c310: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
c320: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
c330: 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
c340: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
c350: 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
c360: 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
c370: 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
c380: 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
c390: 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
c3a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
c3b0: 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
c3c0: 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
c3d0: 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
c3e0: 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
c3f0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
c400: 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
c410: 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
c420: 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
c430: 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
c440: 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
c450: 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
c460: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
c470: 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
c480: 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
c490: 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
c4a0: 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
c4b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
c4c0: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
c4d0: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
c4e0: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
c4f0: 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
c500: 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
c510: 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
c520: 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
c530: 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
c540: 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
c550: 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
c560: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
c570: 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65  xMalloc and xFre
c580: 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
c590: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
c5a0: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
c5b0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
c5c0: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
c5d0: 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68  C library..** Th
c5e0: 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f  e xRealloc metho
c5f0: 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  d must work like
c600: 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20   realloc() from 
c610: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
c620: 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20 74  ibrary.** with t
c630: 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68 61  he exception tha
c640: 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t if the second 
c650: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65 61  argument to xRea
c660: 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  lloc is zero,.**
c670: 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62   xRealloc must b
c680: 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d  e a no-op - it m
c690: 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20  ust not perform 
c6a0: 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  any allocation o
c6b0: 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f  r.** deallocatio
c6c0: 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67 75 61 72  n.  ^SQLite guar
c6d0: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
c6e0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
c6f0: 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
c700: 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
c710: 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
c720: 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
c730: 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f  undup..** And so
c740: 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65 20   in cases where 
c750: 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73 20  xRoundup always 
c760: 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69  returns a positi
c770: 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52  ve number,.** xR
c780: 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f  ealloc can perfo
c790: 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74 68  rm exactly as th
c7a0: 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61  e standard libra
c7b0: 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ry realloc() and
c7c0: 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e 20  .** still be in 
c7d0: 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68 20  compliance with 
c7e0: 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74 69  this specificati
c7f0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  on..**.** xSize 
c800: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
c810: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
c820: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
c830: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
c840: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
c850: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
c860: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
c870: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
c880: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
c890: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
c8a0: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
c8b0: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
c8c0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
c8d0: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
c8e0: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
c8f0: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
c900: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
c910: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c920: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
c930: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
c940: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
c950: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
c960: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
c970: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
c980: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
c990: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
c9a0: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
c9b0: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
c9c0: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
c9d0: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
c9e0: 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
c9f0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
ca00: 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
ca10: 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
ca20: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
ca30: 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
ca40: 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
ca50: 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
ca60: 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
ca70: 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
ca80: 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
ca90: 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
caa0: 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
cab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
cac0: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
cad0: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
cae0: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
caf0: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
cb00: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
cb10: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
cb20: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
cb30: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
cb40: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
cb50: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
cb60: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
cb70: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
cb80: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
cb90: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
cba0: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
cbb0: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
cbc0: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
cbd0: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
cbe0: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
cbf0: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
cc00: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
cc10: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
cc20: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
cc30: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
cc40: 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
cc50: 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
cc60: 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
cc70: 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
cc80: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
cc90: 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
cca0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
ccb0: 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
ccc0: 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
ccd0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
cce0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
ccf0: 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
cd00: 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
cd10: 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
cd20: 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
cd30: 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
cd40: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
cd50: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
cd60: 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
cd70: 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
cd80: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
cd90: 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
cda0: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
cdb0: 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
cdc0: 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
cdd0: 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
cde0: 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
cdf0: 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
ce00: 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
ce10: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
ce20: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
ce30: 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
ce40: 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
ce50: 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
ce60: 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
ce70: 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
ce80: 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
ce90: 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
cea0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
ceb0: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
cec0: 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
ced0: 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
cee0: 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
cef0: 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
cf00: 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
cf10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
cf20: 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
cf30: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
cf40: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
cf50: 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
cf60: 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
cf70: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
cf80: 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
cf90: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
cfa0: 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
cfb0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
cfc0: 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
cfd0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
cfe0: 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
cff0: 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
d000: 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
d010: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
d020: 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
d030: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
d040: 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
d050: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
d060: 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
d070: 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
d080: 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
d090: 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
d0a0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
d0b0: 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
d0c0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
d0d0: 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
d0e0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
d0f0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
d100: 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
d110: 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
d120: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
d130: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
d140: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
d150: 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
d160: 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
d170: 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
d180: 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
d190: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d1a0: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
d1b0: 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
d1c0: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
d1d0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
d1e0: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
d1f0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
d200: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
d210: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
d220: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
d230: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
d240: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
d250: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
d260: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
d270: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
d280: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
d290: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
d2a0: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
d2b0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
d2c0: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
d2d0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
d2e0: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
d2f0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
d300: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
d310: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
d320: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
d330: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
d340: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
d350: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
d360: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
d370: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
d380: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
d390: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
d3a0: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
d3b0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
d3c0: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
d3d0: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
d3e0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
d3f0: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
d400: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
d410: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
d420: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
d430: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
d440: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
d450: 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
d460: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
d470: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
d480: 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
d490: 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
d4a0: 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
d4b0: 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
d4c0: 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
d4d0: 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
d4e0: 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
d4f0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
d500: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
d510: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
d520: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
d530: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
d540: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
d550: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
d560: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
d570: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
d580: 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
d590: 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
d5a0: 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
d5b0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
d5c0: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
d5d0: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
d5e0: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
d5f0: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
d600: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
d610: 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
d620: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
d630: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
d640: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
d650: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
d660: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
d670: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
d680: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
d690: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
d6a0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
d6b0: 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
d6c0: 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
d6d0: 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
d6e0: 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
d6f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d700: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
d710: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
d720: 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
d730: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
d740: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
d750: 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
d760: 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
d770: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
d780: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
d790: 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
d7a0: 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
d7b0: 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
d7c0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
d7d0: 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
d7e0: 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
d7f0: 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
d800: 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
d810: 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
d820: 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
d830: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
d840: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
d850: 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
d860: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
d870: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
d880: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
d890: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
d8a0: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
d8b0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
d8c0: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
d8d0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
d8e0: 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
d8f0: 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
d900: 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
d910: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
d920: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
d930: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
d940: 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
d950: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
d960: 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
d970: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
d980: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d990: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
d9a0: 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
d9b0: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
d9c0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
d9d0: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
d9e0: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
d9f0: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
da00: 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
da10: 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
da20: 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
da30: 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
da40: 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
da50: 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
da60: 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
da70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
da80: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
da90: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
daa0: 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
dab0: 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
dac0: 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
dad0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
dae0: 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
daf0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
db00: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
db10: 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
db20: 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
db30: 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
db40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
db50: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
db60: 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
db70: 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
db80: 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
db90: 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
dba0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
dbb0: 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
dbc0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
dbd0: 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
dbe0: 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
dbf0: 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
dc00: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
dc10: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
dc20: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
dc30: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
dc40: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
dc50: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
dc60: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
dc70: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
dc80: 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
dc90: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
dca0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
dcb0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
dcc0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
dcd0: 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
dce0: 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
dcf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
dd00: 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
dd10: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
dd20: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
dd30: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
dd40: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
dd50: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
dd60: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
dd70: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
dd80: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
dd90: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
dda0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
ddb0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
ddc0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
ddd0: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
dde0: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
ddf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
de00: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
de10: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
de20: 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
de30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
de40: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
de50: 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
de60: 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
de70: 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
de80: 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
de90: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
dea0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
deb0: 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
dec0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
ded0: 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
dee0: 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
def0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
df00: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
df10: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
df20: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
df30: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
df40: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
df50: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
df60: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
df70: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
df80: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
df90: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
dfa0: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
dfb0: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
dfc0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
dfd0: 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
dfe0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
dff0: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
e000: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
e010: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
e020: 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
e030: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
e040: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
e050: 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
e060: 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
e070: 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
e080: 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
e090: 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
e0a0: 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
e0b0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e0c0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
e0d0: 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
e0e0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e0f0: 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
e100: 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
e110: 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
e120: 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
e130: 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
e140: 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
e150: 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
e160: 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
e170: 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
e180: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
e190: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
e1a0: 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  re disabled, the
e1b0: 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   .** following S
e1c0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
e1d0: 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
e1e0: 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
e1f0: 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
e200: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
e210: 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
e220: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
e230: 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
e240: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
e250: 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29  oft_heap_limit()
e260: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
e270: 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
e280: 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
e290: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
e2a0: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
e2b0: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
e2c0: 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
e2d0: 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
e2e0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
e2f0: 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
e300: 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
e310: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
e320: 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
e330: 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
e340: 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
e350: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
e360: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
e370: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
e380: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
e390: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
e3a0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
e3b0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
e3c0: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
e3d0: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
e3e0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
e3f0: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
e400: 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
e410: 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
e420: 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
e430: 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74  e scrach allocat
e440: 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
e450: 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
e460: 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
e470: 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
e480: 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
e490: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
e4a0: 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
e4b0: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
e4c0: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
e4d0: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
e4e0: 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61   16. The sz para
e4f0: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
e500: 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c  a few bytes.** l
e510: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61  arger than the a
e520: 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70  ctual scratch sp
e530: 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65  ace required due
e540: 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65   to internal ove
e550: 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69  rhead..** The fi
e560: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
e570: 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  t be a pointer t
e580: 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  o an 8-byte alig
e590: 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66  ned buffer.** of
e5a0: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
e5b0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
e5c0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
e5d0: 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e  use no more than
e5e0: 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
e5f0: 66 65 72 20 70 65 72 20 74 68 72 65 61 64 2e 20  fer per thread. 
e600: 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
e610: 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 78  be set to the ex
e620: 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
e630: 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
e640: 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a  .  ^SQLite will.
e650: 2a 2a 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ** never require
e660: 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
e670: 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
e680: 68 61 6e 20 36 20 74 69 6d 65 73 20 74 68 65 20  han 6 times the 
e690: 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65  database.** page
e6a0: 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
e6b0: 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
e6c0: 64 69 74 69 6f 6e 61 6c 20 73 63 72 61 74 63 68  ditional scratch
e6d0: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 0a   memory beyond .
e6e0: 2a 2a 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  ** what is provi
e6f0: 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
e700: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
e710: 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
e720: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
e730: 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
e740: 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
e750: 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  needed.</dd>.**.
e760: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e770: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
e780: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
e790: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
e7a0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
e7b0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
e7c0: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
e7d0: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
e7e0: 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
e7f0: 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
e800: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
e810: 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  nation.  .** Thi
e820: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
e830: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
e840: 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
e850: 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
e860: 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
e870: 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
e880: 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
e890: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
e8a0: 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  E option..** The
e8b0: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
e8c0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
e8d0: 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72  ption: A pointer
e8e0: 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   to 8-byte align
e8f0: 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
e900: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
e910: 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
e920: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
e930: 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
e940: 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
e950: 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
e960: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
e970: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
e980: 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
e990: 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
e9a0: 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20  and 32768) plus 
e9b0: 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66  a little extra f
e9c0: 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
e9d0: 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61  header.  ^The pa
e9e0: 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69  ge header size i
e9f0: 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73  s 20 to 40 bytes
ea00: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a   depending on.**
ea10: 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74   the host archit
ea20: 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20  ecture.  ^It is 
ea30: 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
ea40: 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
ea50: 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61  memory,.** to ma
ea60: 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74  ke sz a little t
ea70: 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66  oo large.  The f
ea80: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
ea90: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
eaa0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
eab0: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
eac0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
ead0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
eae0: 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
eaf0: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
eb00: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
eb10: 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
eb20: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
eb30: 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
eb40: 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
eb50: 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20   to cache.  ^If 
eb60: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
eb70: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
eb80: 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
eb90: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
eba0: 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
ebb0: 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
ebc0: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
ebd0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
ebe0: 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
ebf0: 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a  torage space..**
ec00: 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61   ^The implementa
ec10: 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 6f  tion might use o
ec20: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
ec30: 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20 68  e N buffers to h
ec40: 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  old .** memory a
ec50: 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d  ccounting inform
ec60: 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f 69 6e 74  ation. The point
ec70: 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
ec80: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a  argument must.**
ec90: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
eca0: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
ecb0: 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
ecc0: 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
ecd0: 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e  te.** will be un
ece0: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
ecf0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
ed00: 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
ed10: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
ed20: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
ed30: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
ed40: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
ed50: 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
ed60: 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
ed70: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
ed80: 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
ed90: 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
eda0: 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
edb0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
edc0: 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
edd0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
ede0: 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
edf0: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
ee00: 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  : An 8-byte alig
ee10: 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
ee20: 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
ee30: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
ee40: 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
ee50: 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
ee60: 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
ee70: 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
ee80: 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
ee90: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
eea0: 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
eeb0: 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
eec0: 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
eed0: 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
eee0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
eef0: 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
ef00: 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
ef10: 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
ef20: 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
ef30: 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
ef40: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
ef50: 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
ef60: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
ef70: 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
ef80: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
ef90: 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
efa0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
efb0: 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
efc0: 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
efd0: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
efe0: 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
eff0: 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
f000: 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
f010: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f020: 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
f030: 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
f040: 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
f050: 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
f060: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
f070: 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
f080: 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
f090: 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
f0a0: 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
f0b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
f0c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
f0d0: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
f0e0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
f0f0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
f100: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
f110: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
f120: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
f130: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
f140: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
f150: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
f160: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
f170: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
f180: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
f190: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
f1a0: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
f1b0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
f1c0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
f1d0: 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
f1e0: 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
f1f0: 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  .** content of t
f200: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
f210: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
f220: 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
f230: 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
f240: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
f250: 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
f260: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f270: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
f280: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
f290: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f2a0: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
f2b0: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
f2c0: 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
f2d0: 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
f2e0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
f2f0: 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
f300: 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
f310: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f320: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
f330: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
f340: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f350: 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
f360: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
f370: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
f380: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
f390: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
f3a0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
f3b0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
f3c0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
f3d0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
f3e0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
f3f0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f400: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
f410: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
f420: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
f430: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
f440: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
f450: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
f460: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
f470: 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
f480: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
f490: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
f4a0: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
f4b0: 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
f4c0: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
f4d0: 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
f4e0: 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
f4f0: 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
f500: 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
f510: 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
f520: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
f530: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
f540: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
f550: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
f560: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
f570: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
f580: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
f590: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
f5a0: 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
f5b0: 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
f5c0: 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
f5d0: 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
f5e0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
f5f0: 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
f600: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f610: 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
f620: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
f630: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
f640: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
f650: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f660: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
f670: 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
f680: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
f690: 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
f6a0: 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
f6b0: 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
f6c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f6d0: 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  on for the looka
f6e0: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
f6f0: 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a  cator on each.**
f700: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f710: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72  ction].  The fir
f720: 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
f730: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
f740: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
f750: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
f760: 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
f770: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
f780: 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
f790: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
f7a0: 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68  nection.)^  ^(Th
f7b0: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
f7c0: 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74  he.** <i>default
f7d0: 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
f7e0: 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
f7f0: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
f800: 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20  IDE].** verb to 
f810: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
f820: 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
f830: 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
f840: 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
f850: 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
f860: 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
f870: 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
f880: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
f890: 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64 74  ONFIG_PCACHE</dt
f8a0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
f8b0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
f8c0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
f8d0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
f8e0: 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c  er to.** an [sql
f8f0: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
f900: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ods] object.  Th
f910: 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
f920: 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
f930: 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
f940: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
f950: 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e  ementation.)^  ^
f960: 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
f970: 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62  opy of the.** ob
f980: 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74  ject and uses it
f990: 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
f9a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f9b0: 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ns.</dd>.**.** <
f9c0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f9d0: 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a  _GETPCACHE</dt>.
f9e0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
f9f0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
fa00: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
fa10: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
fa20: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
fa30: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
fa40: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  s] object.  SQLi
fa50: 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
fa60: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
fa70: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
fa80: 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
fa90: 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
faa0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
fab0: 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
fac0: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
fad0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
fae0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
faf0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
fb00: 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
fb10: 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
fb20: 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
fb30: 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
fb40: 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
fb50: 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
fb60: 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
fb70: 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
fb80: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
fb90: 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
fba0: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
fbb0: 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
fbc0: 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
fbd0: 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
fbe0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
fbf0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
fc00: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
fc10: 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
fc20: 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
fc30: 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
fc40: 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
fc50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
fc60: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
fc70: 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
fc80: 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
fc90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
fca0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
fcb0: 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
fcc0: 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
fcd0: 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
fce0: 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
fcf0: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
fd00: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
fd10: 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
fd20: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
fd30: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
fd40: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
fd50: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
fd60: 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
fd70: 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
fd80: 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
fd90: 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
fda0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
fdb0: 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
fdc0: 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
fdd0: 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
fde0: 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
fdf0: 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
fe00: 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
fe10: 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
fe20: 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
fe30: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
fe40: 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
fe50: 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
fe60: 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
fe70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
fe80: 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
fe90: 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
fea0: 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
feb0: 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
fec0: 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
fed0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
fee0: 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
fef0: 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
ff00: 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
ff10: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
ff20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
ff30: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
ff40: 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
ff50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
ff60: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
ff70: 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
ff80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
ff90: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
ffa0: 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
ffb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
ffc0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
ffd0: 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
ffe0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
fff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10000 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
10010 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
10020 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
10030 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10040 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
10050 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
10060 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
10070 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
10080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
10090 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
100a0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
100b0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
100c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
100d0 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
100e0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
100f0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
10100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10110 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
10120 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
10130 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10140 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
10150 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
10160 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
10170 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
10180 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10190 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
101a0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
101b0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
101c0 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
101d0 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
101e0 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
101f0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
10200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10210 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
10220 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
10230 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10240 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
10250 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71         14  /* sq
10260 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
10270 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
10280 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
10290 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
102a0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
102b0 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  e_methods* */.#d
102c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
102d0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
102e0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
102f0 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  oid* */../*.** C
10300 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
10310 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
10320 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
10330 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
10340 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
10350 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
10360 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
10370 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
10380 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
10390 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
103a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
103b0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
103c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
103d0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
103e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
103f0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
10400 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
10410 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
10420 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
10430 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
10440 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
10450 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
10460 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
10470 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
10480 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
10490 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
104a0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
104b0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
104c0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
104d0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
104e0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
104f0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
10500 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
10510 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
10520 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
10530 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10540 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
10550 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
10560 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
10570 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
10580 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
10590 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
105a0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
105b0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
105c0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
105d0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
105e0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
105f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
10600 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
10610 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
10620 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10630 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
10640 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
10650 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
10660 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
10670 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66  to an memory buf
10680 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
10690 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
106a0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
106b0 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
106c0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
106d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
106e0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
106f0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
10700 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
10710 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
10720 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
10730 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
10740 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
10750 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10760 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
10770 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
10780 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
10790 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
107a0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
107b0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
107c0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
107d0 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
107e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
107f0 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
10800 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
10810 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
10820 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
10830 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
10840 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
10850 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
10860 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
10870 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
10880 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
10890 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
108a0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
108b0 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
108c0 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
108d0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
108e0 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
108f0 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d  ext smaller.** m
10900 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 53  ultiple of 8.  S
10910 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
10920 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
10930 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  E]</dd>.**.** </
10940 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
10950 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
10960 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31  OOKASIDE    1001
10970 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
10980 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt */.../*.** CA
10990 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
109a0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
109b0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
109c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
109d0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
109e0 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
109f0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
10a00 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
10a10 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
10a20 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
10a30 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
10a40 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
10a50 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
10a60 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
10a70 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
10a80 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
10a90 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
10aa0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
10ab0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
10ac0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
10ad0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
10ae0 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
10af0 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
10b00 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
10b10 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
10b20 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
10b30 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
10b40 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
10b50 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
10b60 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
10b70 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
10b80 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
10b90 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
10ba0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
10bb0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
10bc0 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
10bd0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
10be0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
10bf0 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
10c00 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
10c10 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
10c20 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
10c30 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
10c40 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
10c50 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
10c60 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
10c70 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
10c80 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
10c90 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
10ca0 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
10cb0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
10cc0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
10cd0 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
10ce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
10cf0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10d00 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20  gument.  ^If no 
10d10 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
10d20 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
10d30 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
10d40 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
10d50 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
10d60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
10d70 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
10d80 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
10d90 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
10da0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
10db0 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
10dc0 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
10dd0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
10de0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
10df0 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
10e00 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
10e10 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
10e20 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
10e30 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
10e40 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
10e50 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
10e60 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
10e70 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
10e80 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
10e90 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
10ea0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
10eb0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
10ec0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
10ed0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
10ee0 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
10ef0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
10f00 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
10f10 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
10f20 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
10f30 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
10f40 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
10f50 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
10f60 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
10f70 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
10f80 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
10f90 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
10fa0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
10fb0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
10fc0 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
10fd0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
10fe0 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
10ff0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
11000 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
11010 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
11020 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
11030 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
11040 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
11050 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
11060 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
11070 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
11080 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
11090 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
110a0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
110b0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
110c0 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
110d0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
110e0 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
110f0 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
11100 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
11110 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
11120 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
11130 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
11140 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
11150 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
11160 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
11170 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
11180 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
11190 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
111a0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
111b0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
111c0 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
111d0 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
111e0 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
111f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11200 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
11210 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
11220 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
11230 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
11240 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
11250 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
11260 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
11270 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
11280 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
11290 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
112a0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
112b0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
112c0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
112d0 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
112e0 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
112f0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
11300 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
11310 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
11320 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
11330 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
11340 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
11350 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
11360 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
11370 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
11380 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
11390 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
113a0 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
113b0 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
113c0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
113d0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
113e0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
113f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
11400 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
11410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
11420 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
11430 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
11440 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
11450 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
11460 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
11470 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
11480 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
11490 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
114a0 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
114b0 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
114c0 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
114d0 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
114e0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
114f0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
11500 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
11510 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
11520 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
11530 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
11540 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
11550 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
11560 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
11570 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
11580 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
11590 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
115a0 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
115b0 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
115c0 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
115d0 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
115e0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
115f0 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
11600 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
11610 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
11620 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
11630 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
11640 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
11650 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
11660 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
11670 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
11680 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
11690 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
116a0 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
116b0 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
116c0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
116d0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
116e0 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
116f0 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
11700 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
11710 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
11720 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
11730 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
11740 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
11750 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
11760 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
11770 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
11780 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
11790 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
117a0 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
117b0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
117c0 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
117d0 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
117e0 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
117f0 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
11800 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
11810 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
11820 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
11830 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
11840 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
11850 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
11860 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
11870 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
11880 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
11890 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
118a0 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
118b0 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
118c0 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
118d0 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
118e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
118f0 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
11900 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
11910 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
11920 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
11930 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
11940 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
11950 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
11960 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
11970 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
11980 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
11990 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
119a0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
119b0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
119c0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
119d0 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
119e0 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
119f0 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
11a00 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
11a10 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
11a20 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
11a30 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
11a40 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
11a50 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
11a60 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
11a70 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
11a80 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
11a90 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
11aa0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
11ab0 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
11ac0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
11ad0 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
11ae0 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
11af0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
11b00 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
11b10 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
11b20 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
11b30 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
11b40 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
11b50 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
11b60 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
11b70 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
11b80 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
11b90 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
11ba0 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
11bb0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
11bc0 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
11bd0 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
11be0 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
11bf0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
11c00 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
11c10 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
11c20 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
11c30 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
11c40 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
11c50 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
11c60 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
11c70 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
11c80 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
11c90 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
11ca0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11cb0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
11cc0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
11cd0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
11ce0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
11cf0 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
11d00 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
11d10 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
11d20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
11d30 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
11d40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
11d50 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
11d60 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
11d70 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
11d80 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
11d90 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
11da0 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
11db0 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
11dc0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
11dd0 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
11de0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
11df0 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
11e00 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
11e10 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
11e20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
11e30 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
11e40 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
11e50 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
11e60 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
11e70 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
11e80 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
11e90 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
11ea0 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
11eb0 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
11ec0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
11ed0 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
11ee0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
11ef0 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
11f00 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
11f10 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
11f20 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
11f30 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
11f40 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
11f50 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
11f60 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
11f70 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
11f80 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
11f90 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
11fa0 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
11fb0 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
11fc0 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
11fd0 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
11fe0 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
11ff0 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
12000 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
12010 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
12020 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
12030 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
12040 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
12050 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
12060 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
12070 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
12080 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
12090 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
120a0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
120b0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
120c0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
120d0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
120e0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
120f0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
12100 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
12110 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
12120 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
12130 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
12140 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
12150 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
12160 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
12170 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12180 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
12190 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
121a0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
121b0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
121c0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
121d0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
121e0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
121f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
12200 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
12210 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
12220 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
12230 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
12240 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
12250 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
12260 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
12270 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
12280 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
12290 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
122a0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
122b0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
122c0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
122d0 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
122e0 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
122f0 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
12300 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
12310 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
12320 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
12330 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
12340 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
12350 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
12360 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
12370 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
12380 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
12390 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
123a0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
123b0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
123c0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
123d0 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
123e0 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
123f0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
12400 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
12410 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
12420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
12430 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
12440 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
12450 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
12460 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
12470 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
12480 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
12490 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
124a0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
124b0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
124c0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
124d0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
124e0 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
124f0 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
12500 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
12510 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
12520 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
12530 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
12540 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
12550 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
12560 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
12570 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
12580 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
12590 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
125a0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
125b0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
125c0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
125d0 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
125e0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
125f0 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
12600 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
12610 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
12620 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
12630 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
12640 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12650 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
12660 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
12670 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
12680 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
12690 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
126a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
126b0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
126c0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
126d0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
126e0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
126f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
12700 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
12710 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
12720 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
12730 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
12740 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
12750 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
12760 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
12770 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
12780 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
12790 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
127a0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
127b0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
127c0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
127d0 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
127e0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
127f0 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
12800 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
12810 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
12820 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
12830 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
12840 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
12850 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
12860 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
12870 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
12880 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
12890 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
128a0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
128b0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
128c0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
128d0 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
128e0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
128f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
12900 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
12910 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
12920 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
12930 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
12940 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
12950 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
12960 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
12970 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
12980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12990 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
129a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
129b0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
129c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
129d0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
129e0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
129f0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
12a00 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
12a10 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
12a20 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
12a30 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
12a40 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
12a50 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
12a60 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
12a70 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
12a80 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
12a90 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
12aa0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
12ab0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
12ac0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
12ad0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
12ae0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
12af0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
12b00 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
12b10 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
12b20 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
12b30 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
12b40 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
12b50 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
12b60 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
12b70 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
12b80 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
12b90 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
12ba0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
12bb0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
12bc0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
12bd0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
12be0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
12bf0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
12c00 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
12c10 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
12c20 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
12c30 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
12c40 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
12c50 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
12c60 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
12c70 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
12c80 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
12c90 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
12ca0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
12cb0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
12cc0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
12cd0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
12ce0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
12cf0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
12d00 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
12d10 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
12d20 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
12d30 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
12d40 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
12d50 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
12d60 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
12d70 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
12d80 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
12d90 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
12da0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
12db0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
12dc0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
12dd0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
12de0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
12df0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
12e00 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
12e10 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
12e20 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12e30 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
12e40 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
12e50 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
12e60 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
12e70 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
12e80 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
12e90 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
12ea0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
12eb0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
12ec0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
12ed0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
12ee0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
12ef0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
12f00 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
12f10 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
12f20 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
12f30 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
12f40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
12f50 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
12f60 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
12f70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
12f80 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
12f90 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
12fa0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
12fb0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
12fc0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
12fd0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
12fe0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
12ff0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
13000 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
13010 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
13020 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
13030 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
13040 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
13050 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
13060 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
13070 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
13080 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
13090 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
130a0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
130b0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
130c0 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
130d0 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
130e0 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
130f0 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
13100 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
13110 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
13120 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
13130 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
13140 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
13150 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
13160 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
13170 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
13180 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
13190 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
131a0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
131b0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
131c0 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
131d0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
131e0 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
131f0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
13200 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
13210 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
13220 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
13230 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
13240 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
13250 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
13260 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13270 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
13280 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
13290 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
132a0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
132b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
132c0 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
132d0 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
132e0 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
132f0 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
13300 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
13310 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
13320 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
13330 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
13340 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
13350 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
13360 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
13370 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
13380 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
13390 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
133a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
133b0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
133c0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
133d0 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
133e0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
133f0 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
13400 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
13410 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
13420 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
13430 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
13440 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
13450 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
13460 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
13470 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
13480 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
13490 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
134a0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
134b0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
134c0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
134d0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
134e0 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
134f0 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
13500 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
13510 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
13520 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
13530 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
13540 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
13550 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
13560 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
13570 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
13580 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
13590 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
135a0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
135b0 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
135c0 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
135d0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
135e0 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
135f0 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
13600 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
13610 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
13620 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
13630 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
13640 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
13650 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
13660 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
13670 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
13680 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
13690 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
136a0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
136b0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
136c0 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
136d0 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
136e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
136f0 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
13700 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
13710 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
13720 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
13730 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
13740 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
13750 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
13760 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
13770 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
13780 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
13790 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
137a0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
137b0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
137c0 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
137d0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
137e0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
137f0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
13800 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
13810 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
13820 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
13830 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
13840 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
13850 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
13860 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
13870 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
13880 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
13890 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
138a0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
138b0 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
138c0 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
138d0 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
138e0 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
138f0 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
13900 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
13910 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
13920 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
13930 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
13940 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
13950 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
13960 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
13970 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
13980 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
13990 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
139a0 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
139b0 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
139c0 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
139d0 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
139e0 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
139f0 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
13a00 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
13a10 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
13a20 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
13a30 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
13a40 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
13a50 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
13a60 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
13a70 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
13a80 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
13a90 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
13aa0 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
13ab0 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
13ac0 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
13ad0 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
13ae0 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
13af0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
13b00 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
13b10 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
13b20 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
13b30 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
13b40 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
13b50 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
13b60 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
13b70 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
13b80 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
13b90 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
13ba0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13bb0 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
13bc0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
13bd0 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
13be0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
13bf0 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
13c00 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
13c10 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
13c20 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
13c30 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
13c40 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
13c50 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
13c60 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
13c70 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
13c80 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
13c90 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
13ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13cb0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
13cc0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
13cd0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
13ce0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
13cf0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
13d00 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
13d10 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
13d20 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
13d30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
13d40 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
13d50 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
13d60 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
13d70 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
13d80 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
13d90 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
13da0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
13db0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
13dc0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
13dd0 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
13de0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
13df0 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
13e00 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
13e10 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
13e20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
13e30 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
13e40 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
13e50 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
13e60 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
13e70 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
13e80 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
13e90 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
13ea0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
13eb0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
13ec0 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
13ed0 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
13ee0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
13ef0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
13f00 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
13f10 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
13f20 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
13f30 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
13f40 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
13f50 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
13f60 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
13f70 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
13f80 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
13f90 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
13fa0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
13fb0 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
13fc0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
13fd0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
13fe0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
13ff0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
14000 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
14010 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
14020 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14030 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
14040 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
14050 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
14060 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
14070 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
14080 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
14090 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
140a0 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
140b0 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
140c0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
140d0 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74  leared.)^.*/.int
140e0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
140f0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
14100 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
14110 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
14120 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
14130 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
14140 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  es.**.** Definit
14150 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
14160 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
14170 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
14180 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
14190 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
141a0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
141b0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
141c0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
141d0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
141e0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
141f0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
14200 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
14210 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
14220 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
14230 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
14240 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
14250 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
14260 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
14270 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
14280 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
14290 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
142a0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
142b0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
142c0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
142d0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
142e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
142f0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
14300 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
14310 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
14320 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
14330 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
14340 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
14350 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
14360 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
14370 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
14380 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
14390 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
143a0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
143b0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
143c0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
143d0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
143e0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
143f0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
14400 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
14410 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
14420 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
14430 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
14440 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
14450 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
14460 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
14470 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
14480 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
14490 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
144a0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
144b0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
144c0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
144d0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
144e0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
144f0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
14500 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
14510 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
14520 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
14530 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
14540 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
14550 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
14560 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
14570 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20  )]..**.** As an 
14580 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
14590 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
145a0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
145b0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
145c0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
145d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
145e0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
145f0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
14600 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
14610 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14620 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
14630 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
14640 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
14650 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
14660 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
14670 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
14680 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
14690 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
146a0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
146b0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
146c0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
146d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
146e0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
146f0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
14700 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
14710 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
14720 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
14730 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
14740 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
14750 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
14760 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
14770 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14780 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
14790 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
147a0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
147b0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
147c0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
147d0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
147e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
147f0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
14800 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
14810 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
14820 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
14830 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
14840 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
14850 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
14860 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14870 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
14880 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
14890 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
148a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
148b0 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
148c0 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
148d0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
148e0 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
148f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
14900 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
14910 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
14920 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
14930 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
14940 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
14950 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
14960 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
14970 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
14980 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
14990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
149a0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
149b0 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
149c0 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
149d0 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 73 68  able(),.** it sh
149e0 6f 75 6c 64 20 70 61 73 73 20 74 68 65 20 72 65  ould pass the re
149f0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
14a00 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
14a10 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
14a20 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
14a30 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
14a40 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
14a50 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
14a60 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
14a70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
14a80 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
14a90 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14aa0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
14ab0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
14ac0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
14ad0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
14ae0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
14af0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
14b00 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
14b10 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
14b20 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
14b30 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
14b40 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
14b50 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
14b60 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
14b70 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
14b80 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
14b90 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
14ba0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
14bb0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
14bc0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
14bd0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
14be0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
14bf0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
14c00 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
14c10 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
14c20 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
14c30 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
14c40 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
14c50 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
14c60 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
14c70 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
14c80 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
14c90 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
14ca0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
14cb0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
14cc0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
14cd0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
14ce0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
14cf0 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a 2f  _errmsg()].)^.*/
14d00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
14d10 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
14d20 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
14d30 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
14d40 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
14d50 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
14d60 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
14d70 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
14d80 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
14d90 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
14da0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
14db0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
14dc0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
14dd0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
14de0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
14df0 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
14e00 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
14e10 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
14e20 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
14e30 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
14e40 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
14e50 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
14e60 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
14e70 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14e80 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
14e90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14ea0 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
14eb0 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
14ec0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
14ed0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
14ee0 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
14ef0 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
14f00 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
14f10 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
14f20 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
14f30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
14f40 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
14f50 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
14f60 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
14f70 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
14f80 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
14f90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
14fa0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14fb0 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
14fc0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
14fd0 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
14fe0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
14ff0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
15000 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
15010 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
15020 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
15030 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
15040 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
15050 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
15060 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
15070 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
15080 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
15090 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74  **.** ^(In sqlit
150a0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
150b0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
150c0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
150d0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
150e0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
150f0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
15100 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
15110 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
15120 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
15130 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
15140 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
15150 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
15160 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
15170 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
15180 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
15190 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
151a0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
151b0 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
151c0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
151d0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
151e0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
151f0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
15200 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
15210 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
15220 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
15230 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
15240 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
15250 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
15260 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
15270 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
15280 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
15290 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
152a0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
152b0 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
152c0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
152d0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
152e0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
152f0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
15300 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
15310 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
15320 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
15330 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
15340 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
15350 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
15360 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
15370 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
15380 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
15390 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
153a0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
153b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
153c0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
153d0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
153e0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
153f0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
15400 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
15410 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
15420 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
15430 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
15440 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
15450 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
15460 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
15470 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
15480 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
15490 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
154a0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
154b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
154c0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
154d0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
154e0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
154f0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
15500 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
15510 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
15520 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
15530 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
15540 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
15550 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
15560 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
15570 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
15580 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
15590 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
155a0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
155b0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
155c0 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
155d0 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
155e0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
155f0 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
15600 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
15610 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
15620 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
15630 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
15640 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
15650 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
15660 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
15670 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
15680 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
15690 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
156a0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
156b0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
156c0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
156d0 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
156e0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
156f0 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
15700 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
15710 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
15720 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
15730 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
15740 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
15750 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
15760 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
15770 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
15780 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
15790 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
157a0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
157b0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
157c0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
157d0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
157e0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
157f0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
15800 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
15810 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
15820 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
15830 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
15840 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
15850 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
15860 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
15870 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
15880 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
15890 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
158a0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
158b0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
158c0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
158d0 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
158e0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
158f0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15900 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
15910 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
15920 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
15930 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
15940 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
15950 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
15960 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
15970 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
15980 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
15990 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
159a0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
159b0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
159c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
159d0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
159e0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
159f0 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
15a00 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
15a10 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
15a20 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
15a30 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
15a40 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
15a50 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
15a60 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
15a70 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
15a80 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
15a90 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
15aa0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
15ab0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
15ac0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
15ad0 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
15ae0 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
15af0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
15b00 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
15b10 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
15b20 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
15b30 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
15b40 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
15b50 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
15b60 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
15b70 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
15b80 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
15b90 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
15ba0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
15bb0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
15bc0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
15bd0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15be0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
15bf0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
15c00 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
15c10 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
15c20 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
15c30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
15c40 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
15c50 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
15c60 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
15c70 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
15c80 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
15c90 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
15ca0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
15cb0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
15cc0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
15cd0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
15ce0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
15cf0 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
15d00 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
15d10 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
15d20 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
15d30 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
15d40 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
15d50 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
15d60 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
15d70 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
15d80 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
15d90 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
15da0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
15db0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
15dc0 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
15dd0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
15de0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
15df0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
15e00 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
15e10 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
15e20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
15e30 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
15e40 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
15e50 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
15e60 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
15e70 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
15e80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
15e90 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
15ea0 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
15eb0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
15ec0 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
15ed0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15ee0 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
15ef0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
15f00 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
15f10 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
15f20 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
15f30 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
15f40 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
15f50 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
15f60 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
15f70 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
15f80 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
15f90 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
15fa0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
15fb0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
15fc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
15fd0 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
15fe0 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
15ff0 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
16000 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
16010 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
16020 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16030 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
16040 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
16050 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
16060 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
16070 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
16080 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
16090 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
160a0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
160b0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
160c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
160d0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
160e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
160f0 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
16100 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
16110 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
16120 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
16130 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
16140 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
16150 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
16160 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
16170 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
16180 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
16190 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
161a0 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
161b0 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
161c0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
161d0 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
161e0 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
161f0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
16200 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
16210 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
16220 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
16230 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
16240 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
16250 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
16260 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
16270 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
16280 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
16290 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
162a0 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
162b0 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
162c0 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
162d0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
162e0 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
162f0 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
16300 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
16310 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
16320 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
16330 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
16340 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
16350 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
16360 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
16370 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
16380 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  c()..**.** ^(The
16390 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
163a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
163b0 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
163c0 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
163d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
163e0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
163f0 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
16400 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
16410 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
16420 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
16430 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
16440 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
16450 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20  rameter.)^ ^ If 
16460 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16470 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
16480 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
16490 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
164a0 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
164b0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
164c0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
164d0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65  e3_malloc(N) whe
164e0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
164f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
16500 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16510 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65  )..** ^If the se
16520 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16530 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
16540 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
16550 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
16560 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
16570 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
16580 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
16590 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
165a0 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
165b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
165c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
165d0 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  ()..** ^sqlite3_
165e0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
165f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16600 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16610 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
16620 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
16630 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
16640 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
16650 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
16660 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
16670 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
16680 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
16690 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
166a0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
166b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
166c0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
166d0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
166e0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
166f0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
16700 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
16710 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
16720 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
16730 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16740 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
16750 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
16760 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
16770 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
16780 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
16790 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
167a0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c  malloc() and sql
167b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
167c0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
167d0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
167e0 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
167f0 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ry..**.** In SQL
16800 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
16810 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
16820 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
16830 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
16840 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
16850 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
16860 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
16870 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
16880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
16890 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
168a0 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
168b0 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
168c0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
168d0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
168e0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
168f0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
16900 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
16910 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
16920 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
16930 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
16940 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
16950 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
16960 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
16970 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
16980 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
16990 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
169a0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
169b0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
169c0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
169d0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
169e0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
169f0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
16a00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
16a10 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
16a20 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
16a30 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
16a40 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
16a50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
16a60 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
16a70 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
16a80 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
16a90 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
16aa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
16ab0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
16ac0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
16ad0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
16ae0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
16af0 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
16b00 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
16b10 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
16b20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
16b30 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
16b40 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
16b50 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
16b60 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
16b70 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
16b80 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
16b90 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
16ba0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
16bb0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
16bc0 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
16bd0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
16be0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
16bf0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
16c00 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
16c10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
16c20 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
16c30 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
16c40 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
16c50 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
16c60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16c70 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
16c80 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
16c90 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
16ca0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
16cb0 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
16cc0 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
16cd0 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
16ce0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16cf0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
16d00 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
16d10 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
16d20 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
16d30 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
16d40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16d50 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
16d60 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
16d70 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
16d80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
16d90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
16da0 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
16db0 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
16dc0 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
16dd0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
16de0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
16df0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
16e00 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
16e10 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
16e20 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
16e30 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16e40 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
16e50 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
16e60 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
16e70 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
16e80 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
16e90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
16ea0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
16eb0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
16ec0 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
16ed0 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
16ee0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
16ef0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
16f00 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
16f10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
16f20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
16f30 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
16f40 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
16f50 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
16f60 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
16f70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16f80 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
16f90 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
16fa0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
16fb0 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
16fc0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
16fd0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16fe0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
16ff0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
17000 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
17010 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
17020 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
17030 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
17040 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
17050 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
17060 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
17070 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
17080 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
17090 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
170a0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
170b0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
170c0 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
170d0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
170e0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
170f0 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
17100 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
17110 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
17120 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
17130 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
17140 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
17150 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
17160 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
17170 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
17180 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
17190 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
171a0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
171b0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
171c0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
171d0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
171e0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
171f0 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
17200 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
17210 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
17220 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
17230 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
17240 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
17250 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
17260 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
17270 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
17280 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
17290 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
172a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
172b0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
172c0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
172d0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
172e0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
172f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
17300 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
17310 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
17320 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
17330 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
17340 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
17350 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
17360 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
17370 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
17380 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
17390 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
173a0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
173b0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
173c0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
173d0 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
173e0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
173f0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
17400 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
17410 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
17420 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
17430 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
17440 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
17450 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
17460 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
17470 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
17480 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
17490 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
174a0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
174b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
174c0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
174d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
174e0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
174f0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
17500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
17510 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
17520 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
17530 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
17540 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
17550 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
17560 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
17570 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
17580 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
17590 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
175a0 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
175b0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
175c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
175d0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
175e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
175f0 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
17600 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
17610 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
17620 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
17630 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
17640 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
17650 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
17660 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
17670 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17680 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
17690 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
176a0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
176b0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
176c0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
176d0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
176e0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
176f0 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
17700 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
17710 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
17720 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
17730 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
17740 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
17750 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
17760 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
17770 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
17780 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
17790 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
177a0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
177b0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
177c0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
177d0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
177e0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
177f0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
17800 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
17810 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
17820 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
17830 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
17840 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
17850 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
17860 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
17870 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
17880 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
17890 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
178a0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
178b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
178c0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
178d0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
178e0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
178f0 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
17900 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
17910 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17920 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
17930 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17940 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
17950 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
17960 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
17970 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
17980 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
17990 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
179a0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
179b0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
179c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
179d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
179e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
179f0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
17a00 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
17a10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
17a20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17a30 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
17a40 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
17a50 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
17a60 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
17a70 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
17a80 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
17a90 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
17aa0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
17ab0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
17ac0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
17ad0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
17ae0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
17af0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
17b00 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
17b10 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
17b20 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
17b30 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
17b40 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
17b50 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
17b60 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
17b70 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
17b80 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
17b90 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
17ba0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17bb0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17bc0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
17bd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
17be0 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
17bf0 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
17c00 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
17c10 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
17c20 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
17c30 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
17c40 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
17c50 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
17c60 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
17c70 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
17c80 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
17c90 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
17ca0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
17cb0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
17cc0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
17cd0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
17ce0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
17cf0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
17d00 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
17d10 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
17d20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
17d30 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
17d40 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
17d50 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
17d60 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
17d70 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
17d80 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
17d90 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
17da0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
17db0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
17dc0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
17dd0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
17de0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
17df0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
17e00 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
17e10 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
17e20 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
17e30 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
17e40 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
17e50 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
17e60 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
17e70 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
17e80 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
17e90 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
17ea0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
17eb0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
17ec0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
17ed0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
17ee0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
17ef0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
17f00 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
17f10 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
17f20 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
17f30 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
17f40 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
17f50 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
17f60 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
17f70 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
17f80 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
17f90 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
17fa0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
17fb0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
17fc0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
17fd0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
17fe0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
17ff0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
18000 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
18010 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
18020 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
18030 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
18040 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
18050 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
18060 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
18070 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
18080 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
18090 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
180a0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
180b0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
180c0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
180d0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
180e0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
180f0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
18100 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
18110 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
18120 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
18130 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
18140 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
18150 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
18160 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
18170 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
18180 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18190 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
181a0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
181b0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
181c0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
181d0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
181e0 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
181f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
18200 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
18210 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
18220 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
18230 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
18240 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
18250 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18260 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
18270 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
18280 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
18290 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
182a0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
182b0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
182c0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
182d0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
182e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
182f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
18300 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
18310 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
18320 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
18330 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
18340 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
18350 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
18360 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
18370 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
18380 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
18390 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
183a0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
183b0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
183c0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
183d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
183e0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
183f0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
18400 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
18410 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
18420 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
18430 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
18440 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
18450 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
18460 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
18470 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
18480 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
18490 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
184a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
184b0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
184c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
184d0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
184e0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
184f0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
18500 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
18510 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
18520 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
18530 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
18540 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
18550 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
18560 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
18570 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
18580 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18590 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
185a0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
185b0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
185c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
185d0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
185e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
185f0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
18600 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
18610 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
18620 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
18630 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
18640 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
18650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
18660 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
18670 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
18680 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
18690 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
186a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
186b0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
186c0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
186d0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
186e0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
186f0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
18700 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
18710 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
18720 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
18730 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
18740 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
18750 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
18760 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
18770 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
18780 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
18790 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23  nformation..*/.#
187a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
187b0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
187c0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
187d0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
187e0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
187f0 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
18800 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
18810 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
18820 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
18830 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
18840 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
18850 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
18860 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
18870 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
18880 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
18890 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
188a0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
188b0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
188c0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
188d0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
188e0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
188f0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
18900 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
18910 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
18920 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
18930 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
18940 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
18950 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
18960 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
18970 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
18980 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
18990 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
189a0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
189b0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
189c0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
189d0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
189e0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
189f0 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
18a00 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
18a10 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
18a20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
18a30 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
18a40 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
18a50 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
18a60 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
18a70 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
18a80 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
18a90 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
18aa0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
18ab0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
18ac0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
18ad0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
18ae0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
18af0 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
18b00 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
18b10 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
18b20 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
18b30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
18b40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18b50 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
18b60 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
18b70 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
18b80 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
18b90 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
18ba0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
18bb0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
18bc0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
18bd0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
18be0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
18bf0 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
18c00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18c10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18c20 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
18c30 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
18c40 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
18c50 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18c60 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
18c70 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
18c80 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
18c90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18ca0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18cb0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
18cc0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18cd0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18ce0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18cf0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
18d00 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
18d10 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
18d20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
18d30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18d40 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
18d50 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
18d60 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18d70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18d80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18d90 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
18da0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
18db0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
18dc0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18dd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18de0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
18df0 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
18e00 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
18e10 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e30 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
18e40 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
18e50 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
18e60 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18e70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18e80 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
18e90 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
18ea0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
18eb0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18ec0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18ed0 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
18ee0 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
18ef0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
18f00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18f20 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
18f30 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
18f40 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
18f50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
18f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18f70 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
18f80 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
18f90 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
18fa0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18fb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18fc0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
18fd0 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
18fe0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
18ff0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
19010 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
19020 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
19030 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
19040 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19050 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
19060 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
19070 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
19080 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
19090 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
190a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
190b0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
190c0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
190d0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
190e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
190f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
19100 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
19110 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
19120 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
19130 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19140 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
19150 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
19160 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
19170 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19180 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19190 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
191a0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
191b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
191c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
191d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
191e0 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
191f0 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
19200 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
19210 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
19220 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
19230 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
19240 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
19250 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19260 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
19270 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19280 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
19290 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
192a0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
192b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
192c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
192d0 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
192e0 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
192f0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
19300 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19310 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19320 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
19330 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
19340 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19350 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
19360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19370 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
19380 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
19390 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
193a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
193b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
193c0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
193d0 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
193e0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
193f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19410 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
19420 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
19430 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
19440 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
19450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
19460 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
19470 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
19480 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
19490 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
194a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
194b0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
194c0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
194d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
194e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
194f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19500 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
19510 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
19520 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
19530 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
19540 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
19550 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
19560 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
19570 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
19580 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
19590 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
195a0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
195b0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
195c0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
195d0 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
195e0 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
195f0 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
19600 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
19610 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
19620 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
19630 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
19640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
19650 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
19660 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
19670 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
19680 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
19690 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
196a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
196b0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
196c0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
196d0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
196e0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
196f0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
19700 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
19710 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
19720 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
19730 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
19740 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
19750 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
19760 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
19770 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
19780 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
19790 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
197a0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
197b0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
197c0 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
197d0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
197e0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
197f0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
19800 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
19810 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
19820 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
19830 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
19840 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
19850 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
19860 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
19870 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
19880 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
19890 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
198a0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
198b0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
198c0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
198d0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
198e0 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
198f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
19900 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
19910 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
19920 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
19930 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
19940 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
19950 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
19960 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
19970 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
19980 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
19990 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
199a0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
199b0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
199c0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
199d0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
199e0 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  to run..*/.void 
199f0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
19a00 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
19a10 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
19a20 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
19a30 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
19a40 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
19a50 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
19a60 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
19a70 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
19a80 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
19a90 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
19aa0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
19ab0 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
19ac0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
19ad0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
19ae0 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20  ne configures a 
19af0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19b00 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72  n - the.** progr
19b10 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74  ess callback - t
19b20 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70  hat is invoked p
19b30 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
19b40 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69  ng long.** runni
19b50 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ng calls to [sql
19b60 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
19b70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
19b80 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  nd.** [sqlite3_g
19b90 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e  et_table()].  An
19ba0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
19bb0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
19bc0 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
19bd0 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
19be0 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
19bf0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
19c00 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
19c10 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
19c20 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
19c30 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
19c40 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
19c50 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
19c60 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
19c70 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
19c80 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
19c90 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
19ca0 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
19cb0 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  s handler must n
19cc0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
19cd0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
19ce0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
19cf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
19d00 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
19d10 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
19d20 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
19d30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
19d40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
19d50 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
19d60 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
19d70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
19d80 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
19d90 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
19da0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
19db0 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
19dc0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
19dd0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
19de0 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
19df0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
19e00 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
19e10 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
19e20 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
19e30 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
19e40 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
19e50 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
19e60 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69  whose name is gi
19e70 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69  ven by the.** fi
19e80 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
19e90 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
19ea0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
19eb0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
19ec0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
19ed0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
19ee0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
19ef0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
19f00 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
19f10 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
19f20 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
19f30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19f40 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
19f50 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
19f60 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
19f70 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
19f80 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
19f90 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
19fa0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
19fb0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
19fc0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
19fd0 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
19fe0 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
19ff0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
1a000 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
1a010 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
1a020 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1a030 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
1a040 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
1a050 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
1a060 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
1a070 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
1a080 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
1a090 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
1a0a0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
1a0b0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1a0c0 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
1a0d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1a0e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1a0f0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
1a100 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
1a110 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
1a120 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
1a130 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
1a140 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
1a150 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
1a160 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
1a170 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
1a180 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
1a190 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
1a1a0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
1a1b0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
1a1c0 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
1a1d0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1a1e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1a1f0 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
1a200 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
1a210 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
1a220 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
1a230 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
1a240 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
1a250 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1a260 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
1a270 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
1a280 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1a290 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1a2a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1a2b0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
1a2c0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
1a2d0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
1a2e0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
1a2f0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
1a300 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1a310 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
1a320 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
1a330 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
1a340 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
1a350 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
1a360 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
1a370 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
1a380 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
1a390 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
1a3a0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1a3b0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
1a3c0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
1a3d0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
1a3e0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
1a3f0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
1a400 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
1a410 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
1a420 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
1a430 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1a440 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
1a450 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1a460 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
1a470 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1a480 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53  E],.** and/or [S
1a490 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1a4a0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a 29  TECACHE] flags:)
1a4b0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
1a4c0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1a4d0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
1a4e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1a4f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1a500 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
1a510 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
1a520 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1a530 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
1a540 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1a550 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1a560 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1a570 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
1a580 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a590 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1a5a0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1a5b0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
1a5c0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
1a5d0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
1a5e0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
1a5f0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
1a600 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1a610 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
1a620 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
1a630 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
1a640 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
1a650 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1a660 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
1a670 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1a680 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1a690 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1a6a0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1a6b0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1a6c0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1a6d0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1a6e0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1a6f0 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20  tes it if.** it 
1a700 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
1a710 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
1a720 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
1a730 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
1a740 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1a750 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1a760 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
1a770 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
1a780 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
1a790 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1a7a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1a7b0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
1a7c0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
1a7d0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e  hown above or on
1a7e0 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61  e of the combina
1a7f0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1a800 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69  e combined.** wi
1a810 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
1a820 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
1a830 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1a840 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTEX],.** [SQLIT
1a850 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1a860 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  HE] and/or [SQLI
1a870 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1a880 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74  CHE] flags,.** t
1a890 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1a8a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1a8b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
1a8c0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1a8d0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
1a8e0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1a8f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1a900 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
1a910 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
1a920 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
1a930 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
1a940 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
1a950 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
1a960 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1a970 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
1a980 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
1a990 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1a9a0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
1a9b0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1a9c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
1a9d0 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
1a9e0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
1a9f0 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
1aa00 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
1aa10 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
1aa20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
1aa30 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1aa40 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
1aa50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1aa60 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
1aa70 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1aa80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1aa90 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
1aaa0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
1aab0 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
1aac0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1aad0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
1aae0 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
1aaf0 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
1ab00 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
1ab10 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
1ab20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1ab30 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
1ab40 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
1ab50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ab60 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
1ab70 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
1ab80 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
1ab90 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
1aba0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  abled..**.** ^If
1abb0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1abc0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
1abd0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1abe0 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
1abf0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
1ac00 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
1ac10 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
1ac20 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
1ac30 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
1ac40 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
1ac50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ac60 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
1ac70 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1ac80 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
1ac90 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
1aca0 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
1acb0 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
1acc0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
1acd0 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
1ace0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
1acf0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
1ad00 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1ad10 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
1ad20 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
1ad30 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
1ad40 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
1ad50 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
1ad60 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
1ad70 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
1ad80 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
1ad90 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1ada0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
1adb0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1adc0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1add0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
1ade0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1adf0 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
1ae00 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
1ae10 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
1ae20 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
1ae30 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
1ae40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ae50 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
1ae60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
1ae70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
1ae80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1ae90 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1aea0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1aeb0 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
1aec0 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
1aed0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1aee0 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
1aef0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1af00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
1af10 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
1af20 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1af30 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
1af40 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
1af50 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1af60 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
1af70 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  used..**.** <b>N
1af80 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
1af90 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
1afa0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
1afb0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
1afc0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
1afd0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1afe0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1aff0 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
1b000 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
1b010 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
1b020 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
1b030 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
1b040 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
1b050 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
1b060 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
1b070 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
1b080 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
1b090 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
1b0a0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1b0b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
1b0c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
1b0d0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
1b0e0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1b0f0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1b100 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1b110 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1b120 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1b130 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1b140 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1b150 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
1b160 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
1b170 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1b180 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1b190 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
1b1a0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1b1b0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1b1c0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1b1d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1b1e0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
1b1f0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1b200 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1b210 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1b220 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
1b230 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1b240 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1b250 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
1b260 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1b270 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
1b280 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
1b290 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
1b2a0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
1b2b0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
1b2c0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
1b2d0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
1b2e0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1b2f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
1b300 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1b310 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
1b320 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
1b330 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1b340 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1b350 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
1b360 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
1b370 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
1b380 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
1b390 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b3a0 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
1b3b0 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
1b3c0 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
1b3d0 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
1b3e0 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
1b3f0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
1b400 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1b410 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
1b420 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
1b430 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
1b440 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
1b450 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
1b460 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
1b470 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
1b480 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1b490 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
1b4a0 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
1b4b0 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
1b4c0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
1b4d0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
1b4e0 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
1b4f0 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
1b500 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
1b510 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
1b520 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
1b530 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
1b540 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
1b550 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1b560 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
1b570 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
1b580 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
1b590 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
1b5a0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
1b5b0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
1b5c0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
1b5d0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
1b5e0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
1b5f0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
1b600 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
1b610 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
1b620 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
1b630 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1b640 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
1b650 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
1b660 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  s.)^.**.** When 
1b670 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1b680 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1b690 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
1b6a0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
1b6b0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
1b6c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
1b6d0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1b6e0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
1b6f0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
1b700 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
1b710 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
1b720 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
1b730 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
1b740 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
1b750 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
1b760 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
1b770 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
1b780 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
1b790 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
1b7a0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
1b7b0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
1b7c0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
1b7d0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
1b7e0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
1b7f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
1b800 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
1b810 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
1b820 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
1b830 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
1b840 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
1b850 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
1b860 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
1b870 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
1b880 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
1b890 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
1b8a0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
1b8b0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
1b8c0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
1b8d0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
1b8e0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
1b8f0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
1b900 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1b910 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
1b920 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
1b930 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
1b940 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
1b950 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
1b960 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
1b970 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
1b980 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
1b990 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
1b9a0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
1b9b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
1b9c0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
1b9d0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
1b9e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1b9f0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
1ba00 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1ba10 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1ba20 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1ba30 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
1ba40 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
1ba50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
1ba60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ba70 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
1ba80 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
1ba90 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
1baa0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
1bab0 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
1bac0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
1bad0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
1bae0 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
1baf0 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
1bb00 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
1bb10 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
1bb20 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
1bb30 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
1bb40 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
1bb50 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
1bb60 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
1bb70 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
1bb80 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
1bb90 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
1bba0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
1bbb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1bbc0 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
1bbd0 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
1bbe0 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
1bbf0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
1bc00 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
1bc10 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
1bc20 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
1bc30 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
1bc40 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
1bc50 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
1bc60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
1bc70 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
1bc80 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
1bc90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
1bca0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
1bcb0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
1bcc0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
1bcd0 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
1bce0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
1bcf0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
1bd00 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
1bd10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1bd20 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
1bd30 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
1bd40 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
1bd50 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
1bd60 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
1bd70 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1bd80 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
1bd90 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1bda0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
1bdb0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
1bdc0 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
1bdd0 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28   Limits.**.** ^(
1bde0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1bdf0 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
1be00 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
1be10 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
1be20 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
1be30 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
1be40 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
1be50 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1be60 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
1be70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1be80 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
1be90 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
1bea0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
1beb0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1bec0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
1bed0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
1bee0 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
1bef0 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
1bf00 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
1bf10 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
1bf20 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
1bf30 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
1bf40 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
1bf50 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  uct.  The functi
1bf60 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f  on returns the o
1bf70 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a  ld limit.)^.**.*
1bf80 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
1bf90 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
1bfa0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
1bfb0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
1bfc0 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65 20 6c  ..** ^(For the l
1bfd0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66  imit category of
1bfe0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59   SQLITE_LIMIT_XY
1bff0 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  Z there is a .**
1c000 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
1c010 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
1c020 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65  set by a compile
1c030 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65  -time C preproce
1c040 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64  ssor macro named
1c050 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53   .** [limits | S
1c060 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a  QLITE_MAX_XYZ]..
1c070 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
1c080 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
1c090 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
1c0a0 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
1c0b0 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
1c0c0 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
1c0d0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
1c0e0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
1c0f0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
1c100 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
1c110 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  bound..**.** Run
1c120 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
1c130 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
1c140 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
1c150 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
1c160 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
1c170 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1c180 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
1c190 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
1c1a0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
1c1b0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
1c1c0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
1c1d0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
1c1e0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
1c1f0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
1c200 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
1c210 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
1c220 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
1c230 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
1c240 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
1c250 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
1c260 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
1c270 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
1c280 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
1c290 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1c2a0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
1c2b0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
1c2c0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
1c2d0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
1c2e0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
1c2f0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
1c300 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
1c310 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
1c320 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
1c330 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
1c340 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
1c350 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
1c360 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
1c370 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
1c380 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
1c390 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
1c3a0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
1c3b0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
1c3c0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
1c3d0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
1c3e0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
1c3f0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
1c400 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
1c410 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
1c420 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1c430 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
1c440 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
1c450 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
1c460 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
1c470 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
1c480 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
1c490 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
1c4a0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
1c4b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1c4c0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
1c4d0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
1c4e0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
1c4f0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
1c500 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
1c510 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
1c520 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
1c530 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
1c540 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
1c550 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
1c560 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
1c570 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
1c580 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
1c590 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
1c5a0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
1c5b0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
1c5c0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
1c5d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1c5e0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
1c5f0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
1c600 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
1c610 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  <dl>.** ^(<dt>SQ
1c620 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
1c630 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1c640 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
1c650 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
1c660 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
1c670 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  w.<dd>)^.**.** ^
1c680 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1c690 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
1c6a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c6b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
1c6c0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
1c6d0 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
1c6e0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1c6f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1c700 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
1c710 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c720 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1c730 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
1c740 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
1c750 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
1c760 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
1c770 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c780 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
1c790 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
1c7a0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
1c7b0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
1c7c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1c7d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
1c7e0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
1c7f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c800 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
1c810 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
1c820 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
1c830 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1c840 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
1c850 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
1c860 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c870 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
1c880 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
1c890 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
1c8a0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
1c8b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c8c0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
1c8d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c8e0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
1c8f0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
1c900 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1c910 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
1c920 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
1c930 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
1c940 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1c950 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
1c960 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
1c970 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c980 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
1c990 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
1c9a0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
1c9b0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c9c0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
1c9d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c9e0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1c9f0 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
1ca00 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
1ca10 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28  )^</dd>.**.** ^(
1ca20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1ca30 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1ca40 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1ca50 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1ca60 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
1ca70 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
1ca80 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
1ca90 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
1caa0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1cab0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1cac0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1cad0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
1cae0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1caf0 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e   of variables in
1cb00 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1cb10 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65  t that can.** be
1cb20 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29 5e 0a 2a   bound.</dd>)^.*
1cb30 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1cb40 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
1cb50 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
1cb60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
1cb70 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
1cb80 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
1cb90 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
1cba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1cbb0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
1cbc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1cbd0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
1cbe0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1cbf0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1cc00 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
1cc10 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
1cc20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1cc30 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
1cc40 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
1cc50 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
1cc60 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
1cc70 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1cc80 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
1cc90 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
1cca0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1ccb0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
1ccc0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
1ccd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1cce0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
1ccf0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
1cd00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
1cd10 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
1cd20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
1cd30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1cd40 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
1cd50 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
1cd60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1cd70 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
1cd80 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
1cd90 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1cda0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
1cdb0 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
1cdc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1cdd0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
1cde0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
1cdf0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
1ce00 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
1ce10 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
1ce20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
1ce30 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
1ce40 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
1ce50 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
1ce60 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
1ce70 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
1ce80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1ce90 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
1cea0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
1ceb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
1cec0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
1ced0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
1cee0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1cef0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1cf00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
1cf10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
1cf20 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
1cf30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cf40 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
1cf50 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
1cf60 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
1cf70 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
1cf80 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1cf90 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
1cfa0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
1cfb0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1cfc0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
1cfd0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
1cfe0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1cff0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
1d000 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
1d010 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1d020 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
1d030 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1d040 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
1d050 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
1d060 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
1d070 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
1d080 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
1d090 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
1d0a0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1d0b0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
1d0c0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1d0d0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
1d0e0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
1d0f0 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
1d100 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
1d110 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
1d120 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
1d130 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
1d140 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
1d150 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
1d160 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
1d170 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
1d180 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
1d190 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
1d1a0 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
1d1b0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
1d1c0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
1d1d0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
1d1e0 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
1d1f0 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
1d200 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
1d210 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
1d220 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
1d230 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
1d240 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
1d250 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
1d260 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
1d270 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
1d280 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
1d290 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
1d2a0 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a  tor bytes..**.**
1d2b0 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
1d2c0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
1d2d0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
1d2e0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
1d2f0 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
1d300 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
1d310 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
1d320 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
1d330 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
1d340 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
1d350 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
1d360 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
1d370 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
1d380 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
1d390 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
1d3a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
1d3b0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
1d3c0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
1d3d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
1d3e0 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
1d3f0 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
1d400 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
1d410 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
1d420 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
1d430 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
1d440 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
1d450 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
1d460 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
1d470 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
1d480 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
1d490 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
1d4a0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
1d4b0 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
1d4c0 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
1d4d0 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
1d4e0 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
1d4f0 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
1d500 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1d510 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1d520 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
1d530 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
1d540 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
1d550 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
1d560 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
1d570 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
1d580 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
1d590 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
1d5a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1d5b0 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
1d5c0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1d5d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
1d5e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1d5f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
1d600 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1d610 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
1d620 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
1d630 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
1d640 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
1d650 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
1d660 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
1d670 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
1d680 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1d690 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
1d6a0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
1d6b0 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22  .** ^In the "v2"
1d6c0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
1d6d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1d6e0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
1d6f0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
1d700 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
1d710 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
1d720 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
1d730 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
1d740 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
1d750 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d760 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
1d770 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65  * behave differe
1d780 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61  ntly in three wa
1d790 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
1d7a0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
1d7b0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1d7c0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
1d7d0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
1d7e0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1d7f0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
1d800 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
1d810 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1d820 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
1d830 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
1d840 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
1d850 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
1d860 20 61 67 61 69 6e 2e 20 20 5e 49 66 20 74 68 65   again.  ^If the
1d870 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e   schema has chan
1d880 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20  ged in.** a way 
1d890 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73  that makes the s
1d8a0 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67  tatement no long
1d8b0 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74  er valid, [sqlit
1d8c0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1d8d0 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20  still.** return 
1d8e0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e  [SQLITE_SCHEMA].
1d8f0 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65    But unlike the
1d900 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1d910 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
1d920 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61  ] is.** now a fa
1d930 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c  tal error.  Call
1d940 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1d950 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e  pare_v2()] again
1d960 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74   will not make t
1d970 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61  he.** error go a
1d980 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20  way.  Note: use 
1d990 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1d9a0 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
1d9b0 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
1d9c0 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
1d9d0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
1d9e0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
1d9f0 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  eturn..** </li>.
1da00 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
1da10 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
1da20 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
1da30 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
1da40 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
1da50 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
1da60 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
1da70 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
1da80 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
1da90 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
1daa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
1dab0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
1dac0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
1dad0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
1dae0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
1daf0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
1db00 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
1db10 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
1db20 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1db30 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
1db40 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
1db50 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
1db60 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
1db70 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
1db80 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
1db90 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
1dba0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
1dbb0 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
1dbc0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1dbd0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
1dbe0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
1dbf0 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 5b 70  he value of a [p
1dc00 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
1dc10 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
1dc20 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  e WHERE clause m
1dc30 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ight.** change t
1dc40 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  he query plan fo
1dc50 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  r a statement, t
1dc60 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
1dc70 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61 75 74 6f  t may be.** auto
1dc80 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
1dc90 69 6c 65 64 20 28 61 73 20 69 66 20 74 68 65 72  iled (as if ther
1dca0 65 20 68 61 64 20 62 65 65 6e 20 61 20 73 63 68  e had been a sch
1dcb0 65 6d 61 20 63 68 61 6e 67 65 29 20 6f 6e 20 74  ema change) on t
1dcc0 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 5b 73 71  he first .** [sq
1dcd0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
1dce0 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
1dcf0 20 63 68 61 6e 67 65 20 74 6f 20 74 68 65 20 0a   change to the .
1dd00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1dd10 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
1dd20 5d 20 6f 66 20 74 68 65 20 5b 70 61 72 61 6d 65  ] of the [parame
1dd30 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ter]. .** </li>.
1dd40 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
1dd50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1dd60 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1dd70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1dd80 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1dd90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1dda0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1ddb0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1ddc0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1ddd0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1dde0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1ddf0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1de00 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1de10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1de20 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1de30 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1de40 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1de50 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1de60 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1de70 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1de80 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1de90 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1dea0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
1deb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1dec0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1ded0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1dee0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1def0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1df00 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1df10 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1df20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1df30 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1df40 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1df50 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1df60 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1df70 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1df80 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1df90 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1dfa0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1dfb0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1dfc0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1dfd0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1dfe0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
1dff0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1e000 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1e010 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1e020 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1e030 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1e040 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1e050 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1e060 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1e070 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1e080 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1e090 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1e0a0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1e0b0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1e0c0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1e0d0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1e0e0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1e0f0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1e100 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1e110 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1e120 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1e130 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1e140 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1e150 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1e160 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1e170 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1e180 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1e190 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1e1a0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1e1b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1e1c0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1e1d0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1e1e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1e1f0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1e200 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1e210 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e220 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1e230 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1e240 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1e250 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1e260 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1e270 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1e280 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
1e290 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
1e2a0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
1e2b0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
1e2c0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
1e2d0 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
1e2e0 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
1e2f0 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
1e300 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
1e310 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
1e320 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
1e330 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
1e340 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1e350 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1e360 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
1e370 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1e380 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
1e390 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1e3a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e3b0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
1e3c0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
1e3d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
1e3e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1e3f0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
1e400 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1e410 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
1e420 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
1e430 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
1e440 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
1e450 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
1e460 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
1e470 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
1e480 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
1e490 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
1e4a0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
1e4b0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
1e4c0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
1e4d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1e4e0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
1e4f0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
1e500 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
1e510 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
1e520 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
1e530 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e540 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
1e550 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
1e560 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
1e570 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
1e580 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
1e590 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1e5a0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
1e5b0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
1e5c0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
1e5d0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
1e5e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1e5f0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
1e600 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
1e610 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
1e620 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
1e630 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
1e640 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
1e650 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
1e660 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1e670 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
1e680 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
1e690 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
1e6a0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
1e6b0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
1e6c0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
1e6d0 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  A internal mutex
1e6e0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
1e6f0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1e700 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e710 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
1e720 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
1e730 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1e740 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e750 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
1e760 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
1e770 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
1e780 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
1e790 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
1e7a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
1e7b0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
1e7c0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
1e7d0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
1e7e0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
1e7f0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
1e800 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
1e810 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
1e820 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
1e830 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
1e840 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
1e850 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
1e860 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
1e870 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1e880 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1e890 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
1e8a0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
1e8b0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
1e8c0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
1e8d0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
1e8e0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
1e8f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
1e900 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
1e910 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
1e920 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1e930 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  ween between pro
1e940 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1e950 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1e960 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1e970 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
1e980 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
1e990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e9a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e9b0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
1e9c0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
1e9d0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
1e9e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
1e9f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1ea00 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1ea10 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
1ea20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ea30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
1ea40 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
1ea50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
1ea60 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
1ea70 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
1ea80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1ea90 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
1eaa0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
1eab0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
1eac0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
1ead0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
1eae0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
1eaf0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
1eb00 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
1eb10 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
1eb20 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
1eb30 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
1eb40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1eb50 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
1eb60 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
1eb70 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
1eb80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1eb90 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
1eba0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
1ebb0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
1ebc0 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
1ebd0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
1ebe0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
1ebf0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
1ec00 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
1ec10 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
1ec20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1ec30 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
1ec40 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
1ec50 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
1ec60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1ec70 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
1ec80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
1ec90 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1eca0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
1ecb0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
1ecc0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
1ecd0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
1ece0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
1ecf0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
1ed00 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
1ed10 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
1ed20 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
1ed30 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1ed40 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1ed50 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
1ed60 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
1ed70 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
1ed80 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
1ed90 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
1eda0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
1edb0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
1edc0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
1edd0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
1ede0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
1edf0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
1ee00 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
1ee10 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
1ee20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
1ee30 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
1ee40 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
1ee50 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
1ee60 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
1ee70 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
1ee80 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
1ee90 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ing}.**.** ^(In 
1eea0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1eeb0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
1eec0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1eed0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
1eee0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
1eef0 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
1ef00 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
1ef10 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
1ef20 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
1ef30 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
1ef40 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
1ef50 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
1ef60 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
1ef70 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
1ef80 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
1ef90 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
1efa0 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
1efb0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
1efc0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
1efd0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
1efe0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
1eff0 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
1f000 69 64 65 6e 74 69 66 65 72 2e 29 5e 20 20 5e 54  identifer.)^  ^T
1f010 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
1f020 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
1f030 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
1f040 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1f050 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
1f060 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
1f070 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
1f080 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1f090 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
1f0a0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
1f0b0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1f0c0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
1f0d0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1f0e0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
1f0f0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
1f100 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1f110 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
1f120 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
1f130 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f140 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1f150 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
1f160 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1f170 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1f180 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
1f190 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
1f1a0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1f1b0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1f1c0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
1f1d0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
1f1e0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
1f1f0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
1f200 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
1f210 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
1f220 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
1f230 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
1f240 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
1f250 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
1f260 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
1f270 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
1f280 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
1f290 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
1f2a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f2b0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
1f2c0 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
1f2d0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
1f2e0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
1f2f0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
1f300 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
1f310 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
1f320 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
1f330 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
1f340 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
1f350 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
1f360 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1f370 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
1f380 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
1f390 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
1f3a0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
1f3b0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
1f3c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1f3d0 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
1f3e0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1f3f0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1f400 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1f410 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
1f420 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
1f430 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1f440 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1f450 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1f460 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
1f470 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1f480 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1f490 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
1f4a0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1f4b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
1f4c0 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
1f4d0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
1f4e0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
1f4f0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
1f500 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
1f510 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
1f520 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
1f530 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1f540 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
1f550 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
1f560 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
1f570 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
1f580 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
1f590 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
1f5a0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
1f5b0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
1f5c0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
1f5d0 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66 20 74  d with it. ^If t
1f5e0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1f5f0 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
1f600 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
1f610 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
1f620 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
1f630 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
1f640 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
1f650 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
1f660 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
1f670 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
1f680 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
1f690 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
1f6a0 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
1f6b0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
1f6c0 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
1f6d0 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
1f6e0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
1f6f0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
1f700 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
1f710 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1f720 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1f730 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1f740 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1f750 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
1f760 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
1f770 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
1f780 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
1f790 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
1f7a0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
1f7b0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
1f7c0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
1f7d0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
1f7e0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
1f7f0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
1f800 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
1f810 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
1f820 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
1f830 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
1f840 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
1f850 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
1f860 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
1f870 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
1f880 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
1f890 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
1f8a0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
1f8b0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
1f8c0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
1f8d0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
1f8e0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
1f8f0 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
1f900 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1f910 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
1f920 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1f930 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
1f940 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f950 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
1f960 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f970 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
1f980 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
1f990 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
1f9a0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
1f9b0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
1f9c0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
1f9d0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
1f9e0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
1f9f0 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
1fa00 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
1fa10 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
1fa20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1fa30 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
1fa40 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
1fa50 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
1fa60 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
1fa70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
1fa80 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
1fa90 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
1faa0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
1fab0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
1fac0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
1fad0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
1fae0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
1faf0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
1fb00 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
1fb10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
1fb20 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
1fb30 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
1fb40 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
1fb50 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
1fb60 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
1fb70 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
1fb80 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1fb90 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
1fba0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
1fbb0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
1fbc0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
1fbd0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
1fbe0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1fbf0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1fc00 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
1fc10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1fc20 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
1fc30 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
1fc40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1fc50 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
1fc60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1fc70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1fc80 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1fc90 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
1fca0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1fcb0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
1fcc0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1fcd0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
1fce0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1fcf0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
1fd00 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
1fd10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
1fd20 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
1fd30 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
1fd40 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
1fd50 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
1fd60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1fd70 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1fd80 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
1fd90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1fda0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
1fdb0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1fdc0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1fdd0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
1fde0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1fdf0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
1fe00 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1fe10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1fe20 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
1fe30 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1fe40 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
1fe50 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
1fe60 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
1fe70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1fe80 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
1fe90 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
1fea0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
1feb0 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
1fec0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
1fed0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
1fee0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
1fef0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
1ff00 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1ff10 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
1ff20 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
1ff30 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
1ff40 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
1ff50 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
1ff60 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
1ff70 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
1ff80 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
1ff90 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
1ffa0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1ffb0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
1ffc0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
1ffd0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
1ffe0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
1fff0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
20000 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
20010 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
20020 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
20030 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
20040 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
20050 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
20060 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
20070 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
20080 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
20090 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
200a0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
200b0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
200c0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
200d0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
200e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
200f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
20100 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
20110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
20120 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
20130 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
20140 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20150 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
20160 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20170 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
20180 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
20190 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
201a0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
201b0 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
201c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
201d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
201e0 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
201f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
20200 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
20210 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
20220 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
20230 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
20240 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
20250 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
20260 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
20270 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
20280 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
20290 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
202a0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
202b0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
202c0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
202d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
202e0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
202f0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
20300 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
20310 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
20320 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
20330 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
20340 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
20350 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
20360 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
20370 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
20380 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
20390 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
203a0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
203b0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
203c0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
203d0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
203e0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
203f0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
20400 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
20410 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
20420 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
20430 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
20440 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
20450 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
20460 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
20470 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
20480 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
20490 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
204a0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
204b0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
204c0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
204d0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
204e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
204f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
20500 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
20510 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
20520 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
20530 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
20540 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
20550 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20560 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
20570 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
20580 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
20590 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
205a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
205b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
205c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
205d0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
205e0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
205f0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
20600 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
20610 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
20620 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
20630 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
20640 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
20650 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
20660 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
20670 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
20680 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
20690 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
206a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
206b0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
206c0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
206d0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
206e0 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
206f0 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
20700 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
20710 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
20720 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
20730 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
20740 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
20750 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
20760 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
20770 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20780 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
20790 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
207a0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
207b0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
207c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
207d0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
207e0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
207f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20800 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
20810 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
20820 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
20830 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
20840 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
20850 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20860 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
20870 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
20880 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
20890 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
208a0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
208b0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
208c0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
208d0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
208e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
208f0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
20900 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
20910 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
20920 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
20930 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
20940 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
20950 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
20960 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
20970 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
20980 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20990 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
209a0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
209b0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
209c0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
209d0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
209e0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
209f0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
20a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20a10 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
20a20 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
20a30 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
20a40 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
20a50 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
20a60 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
20a70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
20a80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
20a90 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
20aa0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
20ab0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20ac0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
20ad0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
20ae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
20af0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
20b00 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
20b10 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
20b20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
20b30 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
20b40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
20b50 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
20b60 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
20b70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
20b80 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
20b90 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
20ba0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
20bb0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
20bc0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
20bd0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
20be0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
20bf0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
20c00 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
20c10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
20c20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
20c30 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
20c40 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
20c50 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
20c60 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
20c70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
20c80 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
20c90 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
20ca0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
20cb0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
20cc0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
20cd0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
20ce0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
20cf0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
20d00 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
20d10 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
20d20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
20d30 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
20d40 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
20d50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
20d60 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
20d70 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
20d80 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
20d90 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
20da0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
20db0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
20dc0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
20dd0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
20de0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
20df0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
20e00 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
20e10 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
20e20 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
20e30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
20e40 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
20e50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
20e60 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
20e70 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
20e80 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
20e90 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
20ea0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
20eb0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
20ec0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
20ed0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
20ee0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
20ef0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
20f00 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
20f10 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
20f20 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
20f30 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
20f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
20f50 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
20f60 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
20f70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
20f80 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
20f90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
20fa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20fb0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
20fc0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
20fd0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
20fe0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
20ff0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
21000 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
21010 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
21020 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
21030 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
21040 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
21050 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
21060 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
21070 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
21080 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
21090 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
210a0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
210b0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
210c0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
210d0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
210e0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
210f0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
21100 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
21110 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
21120 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
21130 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
21140 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
21150 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
21160 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
21170 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
21180 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
21190 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
211a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
211b0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
211c0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
211d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
211e0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
211f0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
21200 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
21210 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
21220 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
21230 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
21240 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
21250 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
21260 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
21270 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
21280 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
21290 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
212a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
212b0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
212c0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
212d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
212e0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
212f0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
21300 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
21310 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
21320 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
21330 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
21340 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
21350 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
21360 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
21370 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
21380 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
21390 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
213a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
213b0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
213c0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
213d0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
213e0 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
213f0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
21400 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
21410 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
21420 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
21430 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
21440 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
21450 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
21460 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
21470 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
21480 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
21490 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
214a0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
214b0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
214c0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
214d0 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
214e0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
214f0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
21500 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
21510 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
21520 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
21530 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
21540 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
21550 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
21560 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
21570 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
21580 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
21590 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
215a0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
215b0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
215c0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
215d0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
215e0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
215f0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
21600 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
21610 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
21620 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
21630 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
21640 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
21650 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
21660 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
21670 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
21680 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
21690 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
216a0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
216b0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
216c0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
216d0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
216e0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
216f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
21700 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
21710 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
21720 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
21730 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
21740 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
21750 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
21760 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
21770 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
21780 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
21790 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
217a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
217b0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
217c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
217d0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
217e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
217f0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
21800 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
21810 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
21820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21830 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
21840 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
21850 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21860 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
21870 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
21880 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
21890 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
218a0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
218b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
218c0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
218d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
218e0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
218f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
21900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21910 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
21920 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
21930 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
21940 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
21950 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
21960 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
21970 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
21980 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
21990 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
219a0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
219b0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
219c0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
219d0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
219e0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
219f0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
21a00 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
21a10 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
21a20 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
21a30 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
21a40 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
21a50 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
21a60 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
21a70 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
21a80 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
21a90 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
21aa0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
21ab0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
21ac0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
21ad0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
21ae0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
21af0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
21b00 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21b10 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
21b20 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
21b30 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
21b40 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
21b50 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
21b60 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
21b70 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
21b80 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
21b90 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
21ba0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
21bb0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
21bc0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
21bd0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
21be0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
21bf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
21c00 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
21c10 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
21c20 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
21c30 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
21c40 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
21c50 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
21c60 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
21c70 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
21c80 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
21c90 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
21ca0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
21cb0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
21cc0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
21cd0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
21ce0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
21cf0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
21d00 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
21d10 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
21d20 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
21d30 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
21d40 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
21d50 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
21d60 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
21d70 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
21d80 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
21d90 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
21da0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
21db0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
21dc0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
21dd0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
21de0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
21df0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
21e00 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
21e10 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
21e20 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
21e30 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
21e40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21e50 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
21e60 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
21e70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21e80 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
21e90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21ea0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
21eb0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
21ec0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
21ed0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
21ee0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21ef0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
21f00 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
21f10 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
21f20 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
21f30 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
21f40 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
21f50 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
21f60 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
21f70 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
21f80 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
21f90 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
21fa0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
21fb0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
21fc0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
21fd0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
21fe0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21ff0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
22000 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
22010 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
22020 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
22030 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
22040 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
22050 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
22060 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
22070 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
22080 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
22090 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
220a0 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
220b0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
220c0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
220d0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
220e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
220f0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
22100 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
22110 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
22120 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
22130 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
22140 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
22150 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
22160 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
22170 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
22180 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
22190 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
221a0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
221b0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
221c0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
221d0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
221e0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
221f0 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
22200 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
22210 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
22220 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
22230 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
22240 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
22250 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
22260 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
22270 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
22280 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
22290 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
222a0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
222b0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
222c0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
222d0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
222e0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
222f0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
22300 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
22310 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  a.** explicit tr
22320 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
22330 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
22340 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
22350 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
22360 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
22370 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
22380 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
22390 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
223a0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
223b0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
223c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
223d0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
223e0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
223f0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
22400 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
22410 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
22420 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
22430 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
22440 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
22450 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
22460 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
22470 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
22480 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
22490 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
224a0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
224b0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
224c0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
224d0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
224e0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
224f0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
22500 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
22510 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
22520 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
22530 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
22540 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
22550 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
22560 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
22570 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
22580 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
22590 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
225a0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
225b0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
225c0 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
225d0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
225e0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
225f0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
22600 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
22610 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
22620 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
22630 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
22640 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
22650 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
22660 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
22670 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
22680 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
22690 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
226a0 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
226b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
226c0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
226d0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
226e0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
226f0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
22700 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
22710 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
22720 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
22730 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
22740 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
22750 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
22760 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
22770 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
22780 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
22790 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
227a0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
227b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
227c0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
227d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
227e0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
227f0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
22800 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
22810 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
22820 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
22830 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
22840 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
22850 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
22860 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
22870 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
22880 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
22890 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
228a0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
228b0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
228c0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
228d0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
228e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
228f0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
22900 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
22910 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
22920 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
22930 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
22940 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
22950 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
22960 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
22970 69 74 20 77 61 73 20 72 65 71 75 69 72 65 64 0a  it was required.
22980 2a 2a 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ** after sqlite3
22990 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
229a0 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20   anything other 
229b0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
229c0 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  ] that.** [sqlit
229d0 65 33 5f 72 65 73 65 74 28 29 5d 20 62 65 20 63  e3_reset()] be c
229e0 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 61 6e 79  alled before any
229f0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
22a00 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
22a10 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
22a20 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b 65 20  ilure to invoke 
22a30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22a40 5d 20 69 6e 20 74 68 69 73 20 77 61 79 20 77 6f  ] in this way wo
22a50 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  uld.** result in
22a60 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
22a70 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 20  SE] return from 
22a80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
22a90 20 42 75 74 20 61 66 74 65 72 0a 2a 2a 20 76 65   But after.** ve
22aa0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
22ab0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
22ac0 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b 73 71  egan calling [sq
22ad0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 0a  lite3_reset()] .
22ae0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
22af0 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
22b00 74 61 6e 63 65 20 72 61 74 68 65 72 20 74 68 61  tance rather tha
22b10 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
22b20 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 0a 2a  ITE_MISUSE].  .*
22b30 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
22b40 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
22b50 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
22b60 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
22b70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
22b80 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
22b90 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
22ba0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
22bb0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
22bc0 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
22bd0 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
22be0 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
22bf0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
22c00 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
22c10 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
22c20 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
22c30 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
22c40 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
22c50 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
22c60 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
22c70 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
22c80 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
22c90 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
22ca0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
22cb0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
22cc0 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
22cd0 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
22ce0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
22cf0 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
22d00 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
22d10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
22d20 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
22d30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22d40 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
22d50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
22d60 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
22d70 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
22d80 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
22d90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
22da0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
22db0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
22dc0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
22dd0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
22de0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
22df0 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
22e00 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
22e10 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
22e20 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
22e30 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
22e40 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
22e50 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
22e60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
22e70 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
22e80 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
22e90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
22ea0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
22eb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
22ec0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
22ed0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
22ee0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
22ef0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a  tatement] P..*/.
22f00 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
22f10 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
22f20 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
22f30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
22f40 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
22f50 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
22f60 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
22f70 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
22f80 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
22f90 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
22fa0 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
22fb0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
22fc0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
22fd0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
22fe0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
22ff0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
23000 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
23010 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
23020 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
23030 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
23040 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
23050 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
23060 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
23070 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
23080 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
23090 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
230a0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
230b0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
230c0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
230d0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
230e0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
230f0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
23100 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
23110 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
23120 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
23130 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
23140 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
23150 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
23160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
23170 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
23180 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
23190 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
231a0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
231b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
231c0 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
231d0 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
231e0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
231f0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
23200 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
23210 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
23220 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
23230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23240 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
23250 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
23260 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
23270 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
23280 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
23290 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
232a0 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
232b0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
232c0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
232d0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
232e0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
232f0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
23300 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
23310 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
23320 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
23330 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
23340 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
23350 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
23360 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23370 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
23380 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
23390 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
233a0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
233b0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
233c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
233d0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
233e0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
233f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
23400 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
23410 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
23420 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
23430 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
23440 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
23450 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
23460 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
23470 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
23480 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
23490 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
234a0 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
234b0 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
234c0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
234d0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
234e0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
234f0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
23500 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
23510 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
23520 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
23530 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
23540 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
23550 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
23560 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
23570 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
23580 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
23590 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
235a0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
235b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
235c0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
235d0 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
235e0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
235f0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
23600 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
23610 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
23620 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
23630 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
23640 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
23650 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
23660 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
23670 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
23680 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
23690 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
236a0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
236b0 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
236c0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
236d0 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
236e0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
236f0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
23700 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
23710 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
23720 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23730 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
23740 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
23750 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
23760 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
23770 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
23780 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
23790 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
237a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
237b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
237c0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
237d0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
237e0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
237f0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
23800 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
23810 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
23820 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
23830 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
23840 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
23850 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
23860 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
23870 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
23880 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
23890 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
238a0 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
238b0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
238c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
238d0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
238e0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
238f0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
23900 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
23910 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
23920 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
23930 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
23940 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
23950 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
23960 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
23970 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
23980 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
23990 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
239a0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
239b0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
239c0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
239d0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
239e0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
239f0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
23a00 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
23a10 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
23a20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
23a30 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
23a40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
23a50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
23a60 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
23a70 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
23a80 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
23a90 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
23aa0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
23ab0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
23ac0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
23ad0 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
23ae0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
23af0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
23b00 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
23b10 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
23b20 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
23b30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23b40 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
23b50 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
23b60 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
23b70 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
23b80 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
23b90 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
23ba0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
23bb0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
23bc0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
23bd0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
23be0 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
23bf0 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
23c00 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
23c10 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
23c20 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65  ty: the value re
23c30 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75  turned is the nu
23c40 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
23c50 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
23c60 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
23c70 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
23c80 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
23c90 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
23ca0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
23cb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
23cc0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
23cd0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
23ce0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
23cf0 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
23d00 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
23d10 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
23d20 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
23d30 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
23d40 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62  h BLOB is an arb
23d50 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65  itrary.** pointe
23d60 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e  r, possibly even
23d70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
23d80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23d90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23da0 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  16() routine is 
23db0 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74  similar to sqlit
23dc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23dd0 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20  ).** but leaves 
23de0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54  the result in UT
23df0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
23e00 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61  yte order instea
23e10 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  d of UTF-8..** ^
23e20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  The zero termina
23e30 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  tor is not inclu
23e40 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  ded in this coun
23e50 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  t..**.** ^The ob
23e60 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
23e70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23e80 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
23e90 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
23ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
23eb0 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
23ec0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
23ed0 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
23ee0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
23ef0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
23f00 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
23f10 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
23f20 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
23f30 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
23f40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
23f50 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
23f60 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
23f70 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
23f80 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
23f90 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
23fa0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
23fb0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
23fc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
23fd0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
23fe0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
23ff0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
24000 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
24010 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
24020 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
24030 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
24040 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
24050 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
24060 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
24070 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
24080 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
24090 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
240a0 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
240b0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
240c0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
240d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
240e0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
240f0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
24100 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
24110 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
24120 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
24130 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
24140 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
24150 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
24160 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
24170 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
24180 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
24190 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
241a0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
241b0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
241c0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
241d0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
241e0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
241f0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
24200 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
24210 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
24220 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
24230 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
24240 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
24250 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
24260 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
24270 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
24280 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
24290 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
242a0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
242b0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
242c0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
242d0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
242e0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
242f0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
24300 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
24310 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
24320 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
24330 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
24340 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
24350 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
24360 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
24370 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
24380 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
24390 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
243a0 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
243b0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
243c0 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
243d0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
243e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
243f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
24400 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
24410 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
24420 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
24430 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
24440 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
24450 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
24460 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
24470 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
24480 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
24490 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
244a0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
244b0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
244c0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
244d0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
244e0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
244f0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
24500 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
24510 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
24520 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
24530 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
24540 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
24550 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
24560 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
24570 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
24580 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
24590 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
245a0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
245b0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
245c0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
245d0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
245e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
245f0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
24600 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
24610 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
24620 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
24630 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
24640 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
24650 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
24660 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
24670 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
24680 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
24690 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
246a0 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
246b0 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
246c0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
246d0 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
246e0 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
246f0 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
24700 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
24710 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
24720 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  s..**.** ^Note t
24730 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
24740 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
24750 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
24760 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
24770 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
24780 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
24790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
247a0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
247b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
247c0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
247d0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 5e  nvalidated..** ^
247e0 28 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e  (Type conversion
247f0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
24800 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
24810 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
24820 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
24830 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
24840 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
24850 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
24860 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
24870 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
24880 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
24890 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
248a0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
248b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
248c0 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
248d0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
248e0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
248f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
24900 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
24910 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
24920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24930 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
24940 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
24950 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
24960 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
24970 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
24980 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
24990 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
249a0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
249b0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
249c0 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
249d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
249e0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
249f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24a00 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
24a10 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
24a20 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
24a30 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
24a40 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  </li>.** </ul>)^
24a50 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
24a60 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
24a70 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
24a80 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
24a90 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
24aa0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
24ab0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
24ac0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
24ad0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
24ae0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
24af0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
24b00 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
24b10 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
24b20 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
24b30 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
24b40 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
24b50 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
24b60 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
24b70 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
24b80 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
24b90 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
24ba0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
24bb0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
24bc0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
24bd0 2a 20 5e 28 54 68 65 20 73 61 66 65 73 74 20 61  * ^(The safest a
24be0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
24bf0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
24c00 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
24c10 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
24c20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
24c30 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
24c40 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
24c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24c60 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
24c70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24c80 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
24c90 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
24ca0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
24cb0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
24cc0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
24cd0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
24ce0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
24cf0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
24d00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24d10 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
24d20 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20  /ul>)^.**.** In 
24d30 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
24d40 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
24d50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24d60 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
24d70 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
24d80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24d90 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
24da0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
24db0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
24dc0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
24dd0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
24de0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
24df0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
24e00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
24e10 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
24e20 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
24e30 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
24e40 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
24e50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
24e60 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
24e70 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
24e80 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
24e90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
24ea0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
24eb0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
24ec0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
24ed0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
24ee0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
24ef0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
24f00 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
24f10 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
24f20 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
24f30 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
24f40 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
24f50 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
24f60 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
24f70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
24f80 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
24f90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24fa0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
24fb0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
24fc0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
24fd0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
24fe0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
24ff0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
25000 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
25010 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
25020 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
25030 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
25040 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25050 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
25060 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
25070 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
25080 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
25090 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
250a0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
250b0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
250c0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
250d0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
250e0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
250f0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
25100 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
25110 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
25120 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
25130 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
25140 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
25150 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
25160 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
25170 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
25180 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
25190 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
251a0 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
251b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
251c0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
251d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
251e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
251f0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
25200 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
25210 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
25220 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
25230 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25240 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
25250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
25260 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
25270 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
25280 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
25290 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
252a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
252b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
252c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
252d0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
252e0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
252f0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
25300 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25310 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
25320 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
25330 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
25340 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
25350 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
25360 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
25370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25380 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
25390 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
253a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
253b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
253c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
253d0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
253e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
253f0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
25400 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
25410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
25420 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
25430 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
25440 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
25450 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25460 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  t]..** ^If the s
25470 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65  tatement was exe
25480 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c  cuted successful
25490 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74  ly or not execut
254a0 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a  ed at all, then.
254b0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  ** SQLITE_OK is 
254c0 72 65 74 75 72 6e 65 64 2e 20 5e 49 66 20 65 78  returned. ^If ex
254d0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  ecution of the s
254e0 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20  tatement failed 
254f0 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  then an.** [erro
25500 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  r code] or [exte
25510 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
25520 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
25530 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
25540 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
25550 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
25560 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
25570 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  n of the.** [pre
25580 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25590 2e 20 20 5e 49 66 20 74 68 65 20 76 69 72 74 75  .  ^If the virtu
255a0 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
255b0 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  ot.** completed 
255c0 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74  execution when t
255d0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
255e0 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c  alled, that is l
255f0 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ike.** encounter
25600 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  ing an error or 
25610 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  an [sqlite3_inte
25620 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70  rrupt | interrup
25630 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65  t]..** ^Incomple
25640 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62  te updates may b
25650 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e  e rolled back an
25660 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63  d transactions c
25670 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65  anceled,.** depe
25680 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72  nding on the cir
25690 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20  cumstances, and 
256a0 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  the.** [error co
256b0 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c  de] returned wil
256c0 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f  l be [SQLITE_ABO
256d0 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  RT]..*/.int sqli
256e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
256f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
25700 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25710 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
25720 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
25730 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
25740 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
25750 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
25760 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
25770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25780 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
25790 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
257a0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
257b0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
257c0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
257d0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
257e0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
257f0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
25800 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
25810 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
25820 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
25830 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
25840 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
25850 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
25860 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
25870 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
25880 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
25890 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
258a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
258b0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
258c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
258d0 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
258e0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
258f0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
25900 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
25910 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
25920 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
25930 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
25940 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
25950 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
25960 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
25970 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
25980 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
25990 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
259a0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
259b0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
259c0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
259d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
259e0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
259f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
25a00 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
25a10 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
25a20 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
25a30 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
25a40 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
25a50 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
25a60 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
25a70 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
25a80 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
25a90 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
25aa0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
25ab0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
25ac0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
25ad0 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
25ae0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
25af0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
25b00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25b10 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
25b20 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
25b30 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
25b40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25b50 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
25b60 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
25b70 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
25b80 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
25b90 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
25ba0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
25bb0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
25bc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
25bd0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
25be0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
25bf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
25c00 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74 77 6f 20  *.** ^These two 
25c10 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
25c20 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
25c30 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
25c40 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
25c50 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
25c60 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
25c70 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
25c80 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
25c90 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
25ca0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
25cb0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
25cc0 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
25cd0 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65  difference betwe
25ce0 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73  en the.** two is
25cf0 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
25d00 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20   parameter, the 
25d10 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61  name of the (sca
25d20 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72  lar) function or
25d30 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69  .** aggregate, i
25d40 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
25d50 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  -8 for sqlite3_c
25d60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
25d70 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66   and UTF-16.** f
25d80 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
25d90 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
25da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
25db0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
25dc0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
25dd0 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
25de0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
25df0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
25e00 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
25e10 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
25e20 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
25e30 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
25e40 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
25e50 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
25e60 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
25e70 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
25e80 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
25e90 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
25ea0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  y..**.** The sec
25eb0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
25ec0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25ed0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
25ee0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
25ef0 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
25f00 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
25f10 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
25f20 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65   to 255 bytes, e
25f30 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74  xclusive of.** t
25f40 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
25f50 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
25f60 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
25f70 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
25f80 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
25f90 65 72 73 2e 20 20 5e 41 6e 79 20 61 74 74 65 6d  ers.  ^Any attem
25fa0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
25fb0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
25fc0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
25fd0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
25fe0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e  LITE_ERROR] bein
25ff0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
26000 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
26010 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
26020 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
26030 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
26040 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
26050 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
26060 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
26070 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
26080 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
26090 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
260a0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
260b0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
260c0 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
260d0 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
260e0 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
260f0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
26100 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
26110 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
26120 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
26130 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
26140 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
26150 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
26160 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
26170 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
26180 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
26190 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
261a0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
261b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
261c0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
261d0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
261e0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
261f0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
26200 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63  s.  Any SQL func
26210 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
26220 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62  ion should be ab
26230 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f  le to work.** wo
26240 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  rk with UTF-8, U
26250 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
26260 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
26270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
26280 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
26290 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
262a0 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
262b0 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70  another.  ^An ap
262c0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a  plication may.**
262d0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
262e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
262f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
26300 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
26310 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
26320 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
26330 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
26340 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
26350 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
26360 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
26370 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
26380 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
26390 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
263a0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
263b0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
263c0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
263d0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
263e0 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
263f0 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
26400 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
26410 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
26420 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
26430 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a   care what text.
26440 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  ** encoding is u
26450 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
26460 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
26470 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f  ould be [SQLITE_
26480 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ANY]..**.** ^(Th
26490 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
264a0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
264b0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
264c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
264d0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
264e0 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
264f0 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
26500 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
26510 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
26520 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e  .**.** The seven
26530 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e  th, eighth and n
26540 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  inth parameters,
26550 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
26560 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
26570 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
26580 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
26590 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
265a0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
265b0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
265c0 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
265d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
265e0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
265f0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
26600 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
26610 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
26620 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  s should be pass
26630 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
26640 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
26650 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
26660 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
26670 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
26680 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26690 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
266a0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
266b0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
266c0 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
266d0 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
266e0 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
266f0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
26700 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
26710 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
26720 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  n callbacks..**.
26730 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
26740 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
26750 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
26760 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
26770 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
26780 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
26790 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
267a0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
267b0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
267c0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
267d0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
267e0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
267f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
26800 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
26810 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
26820 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
26830 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
26840 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
26850 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
26860 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
26870 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
26880 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
26890 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
268a0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
268b0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
268c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
268d0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
268e0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
268f0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
26900 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
26910 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
26920 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
26930 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
26940 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
26950 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
26960 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
26970 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
26980 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
26990 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
269a0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
269b0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
269c0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
269d0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
269e0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
269f0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
26a00 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
26a10 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
26a20 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
26a30 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
26a40 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
26a50 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
26a60 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
26a70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
26a80 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
26a90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26aa0 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ed function with
26ab0 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76   a given name ov
26ac0 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62  errides all.** b
26ad0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
26ae0 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  s in the same [d
26af0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26b00 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d  on] with the sam
26b10 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73  e name..** ^Subs
26b20 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69  equent applicati
26b30 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26b40 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
26b50 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72   name only overr
26b60 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70  ide .** prior ap
26b70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26b80 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  d functions that
26b90 20 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61   are an exact ma
26ba0 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e  tch for the.** n
26bb0 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74  umber of paramet
26bc0 65 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65  ers and preferre
26bd0 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  d encoding..**.*
26be0 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
26bf0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
26c00 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
26c10 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
26c20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
26c30 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
26c40 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
26c50 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
26c60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26c70 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
26c80 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
26c90 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
26ca0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
26cb0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
26cc0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
26cd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26ce0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
26cf0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
26d00 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
26d10 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
26d20 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
26d30 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
26d40 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
26d50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
26d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
26d70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
26d80 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
26d90 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
26da0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
26db0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
26dc0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
26dd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
26de0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
26df0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
26e00 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
26e10 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
26e20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
26e30 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
26e40 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
26e50 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
26e60 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
26e70 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
26e80 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
26e90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
26ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
26eb0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
26ec0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
26ed0 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  xt*).);../*.** C
26ee0 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
26ef0 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
26f00 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
26f10 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
26f20 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
26f30 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
26f40 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
26f50 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
26f60 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
26f70 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
26f80 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
26f90 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
26fa0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
26fb0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
26fc0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
26fd0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
26fe0 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
26ff0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
27000 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
27010 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
27020 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
27030 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27040 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
27050 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
27060 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
27070 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
27080 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
27090 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
270a0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
270b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
270c0 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
270d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
270e0 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
270f0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
27100 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
27110 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
27120 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
27130 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
27140 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
27150 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
27160 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
27170 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
27180 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
27190 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
271a0 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
271b0 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
271c0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
271d0 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
271e0 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
271f0 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
27200 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
27210 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
27220 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
27230 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
27240 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
27250 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
27260 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
27270 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
27280 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
27290 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
272a0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
272b0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
272c0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
272d0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
272e0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
272f0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
27300 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
27310 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
27320 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
27330 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
27340 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
27350 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
27360 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
27370 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
27380 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
27390 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
273a0 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
273b0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
273c0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
273d0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
273e0 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
273f0 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
27400 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
27410 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
27420 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
27430 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
27440 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
27450 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
27460 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
27470 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
27480 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
27490 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
274a0 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
274b0 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
274c0 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
274d0 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
274e0 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
274f0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
27500 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27510 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
27520 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27530 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
27540 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
27550 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
27560 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
27570 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
27580 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
27590 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
275a0 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
275b0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
275c0 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
275d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
275e0 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
275f0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
27600 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
27610 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
27620 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
27630 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
27640 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
27650 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
27660 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
27670 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
27680 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
27690 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
276a0 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
276b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
276c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
276d0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
276e0 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
276f0 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
27700 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27710 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
27720 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
27730 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
27740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
27750 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
27760 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
27770 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
27780 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
27790 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
277a0 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
277b0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
277c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
277d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
277e0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
277f0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
27800 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
27810 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
27820 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
27830 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27840 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
27850 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
27860 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
27870 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
27880 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
27890 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
278a0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
278b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
278c0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
278d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
278e0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
278f0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
27900 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
27910 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
27920 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
27930 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
27940 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
27950 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
27960 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
27970 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
27980 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
27990 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
279a0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
279b0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
279c0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
279d0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
279e0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
279f0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
27a00 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
27a10 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
27a20 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
27a30 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
27a40 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
27a50 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
27a60 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
27a70 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
27a80 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
27a90 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
27aa0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
27ab0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
27ac0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
27ad0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
27ae0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
27af0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
27b00 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
27b10 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
27b20 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
27b30 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
27b40 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
27b50 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
27b60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
27b70 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
27b80 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
27b90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
27ba0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
27bb0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
27bc0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
27bd0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
27be0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
27bf0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
27c00 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
27c10 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
27c20 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
27c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27c40 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
27c50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
27c60 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
27c70 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
27c80 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
27c90 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
27ca0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
27cb0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
27cc0 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  eters..*/.const 
27cd0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
27ce0 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
27cf0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
27d00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
27d10 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
27d20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
27d30 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
27d40 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
27d50 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
27d60 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
27d70 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
27d80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
27d90 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
27da0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
27db0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
27dc0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
27dd0 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
27de0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
27df0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
27e00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
27e10 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
27e20 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
27e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27e40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
27e50 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
27e60 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
27e70 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
27e80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27e90 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
27ea0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
27eb0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
27ec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27ed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
27ee0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
27ef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27f00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27f10 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
27f20 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
27f30 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
27f40 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ntions of aggreg
27f50 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
27f60 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
27f70 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
27f80 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
27f90 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
27fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
27fb0 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
27fc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
27fd0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
27fe0 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
27ff0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
28000 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
28010 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
28020 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
28030 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
28040 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
28050 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
28060 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
28070 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
28080 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
28090 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
280a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
280b0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
280c0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
280d0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
280e0 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
280f0 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
28100 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
28110 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
28120 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
28130 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
28140 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
28150 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
28160 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
28170 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
28180 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
28190 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
281a0 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
281b0 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
281c0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
281d0 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
281e0 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
281f0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
28200 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
28210 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
28220 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
28230 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
28240 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
28250 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
28260 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
28270 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
28280 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
28290 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
282a0 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
282b0 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
282c0 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
282d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
282e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
282f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
28300 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73   if N is.** less
28310 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
28320 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
28330 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65  emory allocate e
28340 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
28350 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
28360 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
28370 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
28380 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28390 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
283a0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
283b0 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
283c0 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
283d0 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
283e0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
283f0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
28400 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
28410 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
28420 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
28430 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
28440 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
28450 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
28460 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
28470 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a  location.)^.**.*
28480 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
28490 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
284a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
284b0 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
284c0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
284d0 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
284e0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
284f0 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
28500 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
28510 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
28520 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
28530 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
28540 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
28550 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
28560 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
28570 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
28580 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
28590 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
285a0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
285b0 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
285c0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
285d0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
285e0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
285f0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
28600 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
28610 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
28620 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
28630 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
28640 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28650 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
28660 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
28670 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
28680 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
28690 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
286a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
286b0 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
286c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
286d0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
286e0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
286f0 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
28700 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
28710 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
28720 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
28730 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
28740 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
28750 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
28760 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
28770 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
28780 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
28790 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
287a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
287b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
287c0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
287d0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
287e0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
287f0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
28800 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28810 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
28820 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
28830 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
28840 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
28850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28860 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
28870 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
28880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28890 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
288a0 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
288b0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
288c0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
288d0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
288e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
288f0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
28900 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
28910 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28920 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
28930 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28940 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
28950 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
28960 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
28970 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
28980 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
28990 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
289a0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
289b0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
289c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
289d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
289e0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
289f0 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
28a00 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
28a10 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
28a20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
28a30 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
28a40 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
28a50 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
28a60 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
28a70 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
28a80 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
28a90 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
28aa0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
28ab0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
28ac0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
28ad0 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
28ae0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
28af0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
28b00 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
28b10 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
28b20 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
28b30 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
28b40 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
28b50 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
28b60 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
28b70 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
28b80 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
28b90 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
28ba0 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
28bb0 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
28bc0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
28bd0 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
28be0 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
28bf0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
28c00 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
28c10 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
28c20 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
28c30 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
28c40 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
28c50 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
28c60 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
28c70 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
28c80 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
28c90 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
28ca0 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
28cb0 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
28cc0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
28cd0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
28ce0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
28cf0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
28d00 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
28d10 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
28d20 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
28d30 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
28d40 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
28d50 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
28d60 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
28d70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
28d80 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
28d90 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
28da0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
28db0 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
28dc0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
28dd0 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
28de0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
28df0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
28e00 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
28e10 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
28e20 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
28e30 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
28e40 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
28e50 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
28e60 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
28e70 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
28e80 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
28e90 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
28ea0 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
28eb0 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
28ec0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
28ed0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
28ee0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
28ef0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
28f00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28f10 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
28f20 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
28f30 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
28f40 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
28f50 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
28f60 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
28f70 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
28f80 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
28f90 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
28fa0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
28fb0 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
28fc0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
28fd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
28fe0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
28ff0 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
29000 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
29010 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
29020 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
29030 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
29040 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
29050 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
29060 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
29070 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
29080 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
29090 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
290a0 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
290b0 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
290c0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
290d0 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
290e0 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
290f0 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
29100 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
29110 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
29120 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
29130 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
29140 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
29150 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
29160 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
29170 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
29180 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
29190 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
291a0 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
291b0 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
291c0 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
291d0 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
291e0 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
291f0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
29200 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
29210 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
29220 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
29230 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
29240 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
29250 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
29260 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
29270 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29280 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
29290 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
292a0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
292b0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
292c0 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
292d0 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
292e0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
292f0 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
29300 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
29310 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
29320 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
29330 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
29340 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
29350 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
29360 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
29370 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
29380 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
29390 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
293a0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
293b0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
293c0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
293d0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
293e0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
293f0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
29400 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
29410 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
29420 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
29430 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
29440 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
29450 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
29460 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
29470 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
29480 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
29490 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
294a0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
294b0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
294c0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
294d0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
294e0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
294f0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
29500 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
29510 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
29520 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
29530 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
29540 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
29550 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
29560 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
29570 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
29580 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
29590 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
295a0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
295b0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
295c0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
295d0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
295e0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
295f0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
29600 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
29610 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
29620 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
29630 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
29640 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
29650 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
29660 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
29670 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
29680 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
29690 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
296a0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
296b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
296c0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
296d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
296e0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
296f0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
29700 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
29710 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
29720 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
29730 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
29740 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
29750 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
29760 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
29770 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
29780 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
29790 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
297a0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
297b0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
297c0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
297d0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
297e0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
297f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29800 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
29810 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
29820 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
29830 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29840 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
29850 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
29860 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
29870 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
29880 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
29890 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
298a0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
298b0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
298c0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
298d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
298e0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
298f0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
29900 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
29910 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
29920 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29930 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
29940 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
29950 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
29960 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
29970 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
29980 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
29990 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
299a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
299b0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
299c0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
299d0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
299e0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
299f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
29a00 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
29a10 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
29a20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
29a30 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
29a40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29a50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29a60 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
29a70 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
29a80 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
29a90 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
29aa0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
29ab0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
29ac0 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
29ad0 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
29ae0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
29af0 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
29b00 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
29b10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
29b20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
29b30 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
29b40 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
29b50 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
29b60 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
29b70 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
29b80 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
29b90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
29ba0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
29bb0 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
29bc0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
29bd0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
29be0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29bf0 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
29c00 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
29c10 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
29c20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
29c30 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
29c40 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
29c50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29c60 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
29c70 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
29c80 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
29c90 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
29ca0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
29cb0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
29cc0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
29cd0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
29ce0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
29cf0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29d00 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
29d10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
29d20 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
29d30 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
29d40 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
29d50 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
29d60 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
29d70 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
29d80 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
29d90 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
29da0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29db0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
29dc0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
29dd0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
29de0 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
29df0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
29e00 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
29e10 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
29e20 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
29e30 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
29e40 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
29e50 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
29e60 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
29e70 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
29e80 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
29e90 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29ea0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
29eb0 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
29ec0 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
29ed0 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
29ee0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
29ef0 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
29f00 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
29f10 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
29f20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
29f30 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
29f40 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
29f50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29f60 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
29f70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
29f80 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
29f90 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
29fa0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
29fb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29fc0 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
29fd0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
29fe0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
29ff0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
2a000 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
2a010 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
2a020 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
2a030 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2a040 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2a050 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
2a060 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2a070 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
2a080 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
2a090 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
2a0a0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
2a0b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a0c0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
2a0d0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2a0e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2a0f0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2a100 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2a110 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2a120 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
2a130 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
2a140 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
2a150 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2a160 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a170 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
2a180 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2a190 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2a1a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2a1b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2a1c0 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
2a1d0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2a1e0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2a1f0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2a200 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2a210 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2a220 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
2a230 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2a240 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2a250 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a260 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2a270 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
2a280 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2a290 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
2a2a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2a2b0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
2a2c0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
2a2d0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
2a2e0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
2a2f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
2a300 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
2a310 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
2a320 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2a330 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
2a340 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
2a350 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
2a360 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
2a370 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
2a380 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
2a390 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
2a3a0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
2a3b0 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
2a3c0 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
2a3d0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
2a3e0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
2a3f0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
2a400 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
2a410 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
2a420 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2a430 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
2a440 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2a450 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2a460 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2a470 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2a480 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2a490 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
2a4a0 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
2a4b0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2a4c0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
2a4d0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
2a4e0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
2a4f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2a500 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2a510 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2a520 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
2a530 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
2a540 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
2a550 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
2a560 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
2a570 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
2a580 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
2a590 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
2a5a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2a5b0 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
2a5c0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
2a5d0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2a5e0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2a5f0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2a600 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2a610 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2a620 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
2a630 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2a640 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
2a650 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
2a660 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
2a670 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
2a680 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
2a690 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
2a6a0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
2a6b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
2a6c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2a6d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2a6e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2a6f0 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
2a700 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2a710 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
2a720 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
2a730 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
2a740 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
2a750 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
2a760 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
2a770 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
2a780 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
2a790 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
2a7a0 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
2a7b0 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
2a7c0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
2a7d0 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
2a7e0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
2a7f0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
2a800 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
2a810 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2a820 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a830 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2a840 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2a850 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
2a860 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
2a870 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
2a880 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
2a890 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
2a8a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
2a8b0 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
2a8c0 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
2a8d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2a8e0 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
2a8f0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2a900 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2a910 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2a920 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2a930 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2a940 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2a950 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2a960 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
2a970 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a980 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
2a990 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2a9a0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
2a9b0 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
2a9c0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2a9d0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
2a9e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
2a9f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2aa00 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
2aa10 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
2aa20 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
2aa30 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
2aa40 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
2aa50 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
2aa60 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2aa70 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
2aa80 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
2aa90 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2aaa0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2aab0 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
2aac0 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
2aad0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2aae0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2aaf0 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
2ab00 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
2ab10 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
2ab20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
2ab30 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
2ab40 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
2ab50 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
2ab60 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2ab70 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
2ab80 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2ab90 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
2aba0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2abb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2abc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
2abd0 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
2abe0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
2abf0 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
2ac00 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2ac10 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  efined..*/.void 
2ac20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2ac30 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2ac40 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2ac50 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2ac60 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2ac70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
2ac80 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
2ac90 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
2aca0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2acb0 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
2acc0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2acd0 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
2ace0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2acf0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
2ad00 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2ad10 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
2ad20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2ad30 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
2ad40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ad50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2ad60 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
2ad70 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
2ad80 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2ad90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2ada0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
2adb0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2adc0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2add0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
2ade0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2adf0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2ae00 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
2ae10 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2ae20 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
2ae30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
2ae40 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
2ae50 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
2ae60 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
2ae70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2ae80 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2ae90 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2aea0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2aeb0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
2aec0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2aed0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2aee0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2aef0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2af00 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2af10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2af20 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2af30 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2af40 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2af50 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2af60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2af70 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2af80 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2af90 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2afa0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
2afb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2afc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2afd0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2afe0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
2aff0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b000 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
2b010 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
2b020 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
2b030 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54  equences.**.** T
2b040 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
2b050 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e  re used to add n
2b060 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
2b070 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a  uences to the.**
2b080 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2b090 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
2b0a0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
2b0b0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2b0c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
2b0d0 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
2b0e0 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69  uence is specifi
2b0f0 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74  ed as a UTF-8 st
2b100 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
2b110 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2b120 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
2b130 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b140 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
2b150 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2b160 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2b170 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
2b180 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a  . ^In all cases.
2b190 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70  ** the name is p
2b1a0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
2b1b0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2b1c0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
2b1d0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2b1e0 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74   may be one of t
2b1f0 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51  he constants [SQ
2b200 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b  LITE_UTF8],.** [
2b210 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
2b220 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
2b230 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
2b240 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
2b250 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
2b260 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
2b270 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
2b280 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
2b290 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
2b2a0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
2b2b0 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e-endian, or UTF
2b2c0 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20  -16 big-endian, 
2b2d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e 54  respectively. ^T
2b2e0 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75  he.** third argu
2b2f0 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20  ment might also 
2b300 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  be [SQLITE_UTF16
2b310 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  ] to indicate th
2b320 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a  at the routine.*
2b330 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65  * expects pointe
2b340 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36 20  rs to be UTF-16 
2b350 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 6e  strings in the n
2b360 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2b370 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67 75  , or the.** argu
2b380 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51 4c  ment can be [SQL
2b390 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2b3a0 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65  D] if the.** the
2b3b0 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
2b3c0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
2b3d0 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
2b3e0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
2b3f0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
2b400 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
2b410 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
2b420 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70  to the user supp
2b430 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73  lied routine mus
2b440 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
2b450 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75  he fifth.** argu
2b460 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69 73  ment.  ^If it is
2b470 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
2b480 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
2b490 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
2b4a0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
2b4b0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
2b4c0 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
2b4d0 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20  more)..** ^Each 
2b4e0 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61  time the applica
2b4f0 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75  tion supplied fu
2b500 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
2b510 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a  d, it is passed.
2b520 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20  ** as its first 
2b530 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79  parameter a copy
2b540 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61   of the void* pa
2b550 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
2b560 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
2b570 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2b580 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20  _collation() or 
2b590 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b5a0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
2b5b0 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e 69  .** ^The remaini
2b5c0 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ng arguments to 
2b5d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2b5e0 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65  supplied routine
2b5f0 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73   are two strings
2b600 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73  ,.** each repres
2b610 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67  ented by a (leng
2b620 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61  th, data) pair a
2b630 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68  nd encoded in th
2b640 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68  e encoding.** th
2b650 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73  at was passed as
2b660 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
2b670 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  ent when the col
2b680 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2b690 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  was.** registere
2b6a0 64 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  d.  The applicat
2b6b0 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c  ion defined coll
2b6c0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68  ation routine sh
2b6d0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e  ould.** return n
2b6e0 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72  egative, zero or
2b6f0 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65   positive if the
2b700 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
2b710 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65   less than,.** e
2b720 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
2b730 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
2b740 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e  ond string. i.e.
2b750 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49   (STRING1 - STRI
2b760 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NG2)..**.** ^The
2b770 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b780 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
2b790 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
2b7a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2b7b0 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  on().** except t
2b7c0 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20  hat it takes an 
2b7d0 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77  extra argument w
2b7e0 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75  hich is a destru
2b7f0 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ctor for.** the 
2b800 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65  collation.  ^The
2b810 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2b820 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63  alled when the c
2b830 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  ollation is.** d
2b840 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20  estroyed and is 
2b850 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
2b860 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2b870 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e  meter void* poin
2b880 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ter.** of the sq
2b890 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2b8a0 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20  lation_v2()..** 
2b8b0 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20  ^Collations are 
2b8c0 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74  destroyed when t
2b8d0 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
2b8e0 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c  en by later call
2b8f0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c  s to the.** coll
2b900 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
2b910 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
2b920 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2b930 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
2b940 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  osed.** using [s
2b950 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
2b960 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2b970 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
2b980 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
2b990 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
2b9a0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2b9b0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2b9c0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2b9d0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
2b9e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2b9f0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
2ba00 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2ba10 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2ba20 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2ba30 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2ba40 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
2ba50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ba60 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
2ba70 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
2ba80 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
2ba90 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
2baa0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
2bab0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2bac0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2bad0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2bae0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
2baf0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
2bb00 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2bb10 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
2bb20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2bb30 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
2bb40 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2bb50 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
2bb60 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2bb70 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2bb80 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2bb90 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2bba0 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
2bbb0 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
2bbc0 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
2bbd0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
2bbe0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
2bbf0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
2bc00 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
2bc10 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
2bc20 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
2bc30 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
2bc40 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
2bc50 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
2bc60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2bc70 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2bc80 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
2bc90 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
2bca0 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
2bcb0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
2bcc0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
2bcd0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2bce0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
2bcf0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
2bd00 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
2bd10 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
2bd20 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
2bd30 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2bd40 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
2bd50 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
2bd60 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
2bd70 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2bd80 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
2bd90 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
2bda0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
2bdb0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
2bdc0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
2bdd0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
2bde0 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
2bdf0 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
2be00 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
2be10 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
2be20 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
2be30 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
2be40 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
2be50 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
2be60 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
2be70 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2be80 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
2be90 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
2bea0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2beb0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2bec0 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
2bed0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
2bee0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2bef0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
2bf00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
2bf10 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
2bf20 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2bf30 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
2bf40 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
2bf50 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
2bf60 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
2bf70 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
2bf80 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
2bf90 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
2bfa0 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
2bfb0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2bfc0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
2bfd0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
2bfe0 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
2bff0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
2c000 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
2c010 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
2c020 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
2c030 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2c040 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2c050 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
2c060 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2c070 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2c080 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2c090 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
2c0a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2c0b0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
2c0c0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2c0d0 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
2c0e0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
2c0f0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
2c100 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
2c110 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2c120 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
2c130 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
2c140 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2c150 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2c160 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
2c170 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
2c180 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
2c190 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2c1a0 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
2c1b0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
2c1c0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
2c1d0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
2c1e0 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
2c1f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
2c200 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2c210 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2c220 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2c230 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2c240 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2c250 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2c260 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
2c270 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2c280 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c290 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2c2a0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2c2b0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2c2c0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2c2d0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
2c2e0 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
2c2f0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
2c300 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
2c310 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
2c320 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
2c330 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
2c340 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
2c350 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
2c360 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
2c370 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
2c380 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
2c390 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
2c3a0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
2c3b0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
2c3c0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
2c3d0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
2c3e0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2c3f0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
2c400 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2c410 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2c420 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2c430 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2c440 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2c450 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
2c460 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
2c470 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2c480 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2c490 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73  or a SEE databas
2c4a0 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
2c4b0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
2c4c0 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e  f the SEE routin
2c4d0 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
2c4e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
2c4f0 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f  tivate_see(.  co
2c500 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
2c510 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
2c520 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
2c530 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
2c540 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e  #ifdef SQLITE_EN
2c550 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a  ABLE_CEROD./*.**
2c560 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
2c570 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
2c580 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65  a CEROD database
2c590 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
2c5a0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
2c5b0 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69   the CEROD routi
2c5c0 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
2c5d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
2c5e0 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
2c5f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2c600 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2c610 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2c620 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2c630 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
2c640 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
2c650 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
2c660 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Time.**.** ^The
2c670 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
2c680 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
2c690 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
2c6a0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
2c6b0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
2c6c0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
2c6d0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2c6e0 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
2c6f0 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
2c700 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 65 72  .** ^If the oper
2c710 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
2c720 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
2c730 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
2c740 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
2c750 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
2c760 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
2c770 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
2c780 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
2c790 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 5e 54 68  rest second. ^Th
2c7a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
2c7b0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
2c7c0 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
2c7d0 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
2c7e0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2c7f0 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
2c800 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
2c810 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
2c820 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
2c830 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
2c840 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
2c850 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
2c860 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
2c870 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
2c880 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
2c890 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
2c8a0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
2c8b0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
2c8c0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
2c8d0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
2c8e0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
2c8f0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
2c900 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
2c910 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
2c920 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
2c930 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
2c940 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
2c950 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
2c960 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
2c970 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69  a built-in [sqli
2c980 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a  te3_vfs | VFS].*
2c990 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  * will be placed
2c9a0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
2c9b0 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20  ry.)^  ^If this 
2c9c0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
2c9d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
2c9e0 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
2c9f0 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
2ca00 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
2ca10 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
2ca20 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
2ca30 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
2ca40 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
2ca50 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2ca60 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
2ca70 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
2ca80 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
2ca90 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
2caa0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
2cab0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
2cac0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2cad0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
2cae0 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
2caf0 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
2cb00 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
2cb10 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
2cb20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
2cb30 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
2cb40 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
2cb50 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
2cb60 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
2cb70 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
2cb80 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
2cb90 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2cba0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
2cbb0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
2cbc0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
2cbd0 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
2cbe0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2cbf0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2cc00 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
2cc10 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
2cc20 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
2cc30 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
2cc40 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2cc50 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
2cc60 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
2cc70 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2cc80 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2cc90 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
2cca0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
2ccb0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
2ccc0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
2ccd0 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
2cce0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2ccf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
2cd00 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
2cd10 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
2cd20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
2cd30 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
2cd40 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
2cd50 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
2cd60 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
2cd70 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
2cd80 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
2cd90 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
2cda0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
2cdb0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
2cdc0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2cdd0 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
2cde0 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
2cdf0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2ce00 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2ce10 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
2ce20 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  ed..*/.SQLITE_EX
2ce30 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
2ce40 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
2ce50 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
2ce60 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
2ce70 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a  o-Commit Mode.**
2ce80 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f   KEYWORDS: {auto
2ce90 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a  commit mode}.**.
2cea0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ceb0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
2cec0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ced0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
2cee0 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
2cef0 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
2cf00 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
2cf10 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
2cf20 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
2cf30 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f  ectively.  ^Auto
2cf40 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
2cf50 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
2cf60 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
2cf70 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2cf80 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
2cf90 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ment..** ^Autoco
2cfa0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
2cfb0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
2cfc0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
2cfd0 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
2cfe0 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
2cff0 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
2d000 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
2d010 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
2d020 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
2d030 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
2d040 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
2d050 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
2d060 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
2d070 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
2d080 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
2d090 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
2d0a0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
2d0b0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
2d0c0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
2d0d0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
2d0e0 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
2d0f0 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
2d100 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
2d110 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
2d120 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2d130 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
2d140 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
2d150 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2d160 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
2d170 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
2d180 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
2d190 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2d1a0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
2d1b0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
2d1c0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
2d1d0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
2d1e0 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
2d1f0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
2d200 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
2d210 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
2d220 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2d230 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
2d240 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
2d250 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2d260 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d270 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74  e3_db_handle int
2d280 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2d290 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2d2a0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
2d2b0 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70  ** to which a [p
2d2c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d2d0 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68  t] belongs.  ^Th
2d2e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2d2f0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72  ection].** retur
2d300 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64  ned by sqlite3_d
2d310 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20  b_handle is the 
2d320 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2d330 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68  onnection].** th
2d340 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74  at was the first
2d350 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2d360 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
2d370 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20  pare_v2()] call 
2d380 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73  (or its variants
2d390 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  ) that was used 
2d3a0 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65  to.** create the
2d3b0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
2d3c0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
2d3d0 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
2d3e0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  e3_db_handle(sql
2d3f0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2d400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
2d410 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  nd the next prep
2d420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2d430 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
2d440 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2d450 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65  ointer to the ne
2d460 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  xt [prepared sta
2d470 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a  tement] after.**
2d480 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65   pStmt associate
2d490 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
2d4a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2d4b0 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74   pDb.  ^If pStmt
2d4c0 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e   is NULL.** then
2d4d0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2d4e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2d4f0 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70  r to the first p
2d500 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d510 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  t.** associated 
2d520 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
2d530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62  e connection pDb
2d540 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72  .  ^If no prepar
2d550 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2d560 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f  satisfies the co
2d570 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73  nditions of this
2d580 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74   routine, it ret
2d590 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  urns NULL..**.**
2d5a0 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
2d5b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74  onnection] point
2d5c0 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74  er D in a call t
2d5d0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65  o.** [sqlite3_ne
2d5e0 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75  xt_stmt(D,S)] mu
2d5f0 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f  st refer to an o
2d600 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  pen database.** 
2d610 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69  connection and i
2d620 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73  n particular mus
2d630 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20  t not be a NULL 
2d640 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69  pointer..*/.sqli
2d650 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65  te3_stmt *sqlite
2d660 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69  3_next_stmt(sqli
2d670 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65  te3 *pDb, sqlite
2d680 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2d690 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d6a0 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c   Commit And Roll
2d6b0 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f  back Notificatio
2d6c0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
2d6d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2d6e0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
2d6f0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2d700 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2d710 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2d720 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2d730 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2d740 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74  [COMMIT | commit
2d750 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ted]..** ^Any ca
2d760 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2d770 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2d780 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
2d790 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
2d7a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2d7b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
2d7c0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
2d7d0 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
2d7e0 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
2d7f0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2d800 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
2d810 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
2d820 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
2d830 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f  ansaction is [RO
2d840 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20  LLBACK | rolled 
2d850 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  back]..** ^Any c
2d860 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2d870 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2d880 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  o sqlite3_rollba
2d890 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  ck_hook().** for
2d8a0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2d8b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d8c0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2d8d0 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65  ^The pArg argume
2d8e0 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
2d8f0 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
2d900 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  back..** ^If the
2d910 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
2d920 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
2d930 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ion returns non-
2d940 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  zero,.** then th
2d950 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
2d960 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
2d970 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
2d980 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
2d990 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64  _hook(D,C,P) and
2d9a0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
2d9b0 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  k_hook(D,C,P) fu
2d9c0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
2d9d0 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  n the P argument
2d9e0 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
2d9f0 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73  us call of the s
2da00 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
2da10 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2da20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2da30 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2da40 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2da50 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63  ll for each func
2da60 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  tion on D..**.**
2da70 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
2da80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2da90 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
2daa0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
2dab0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
2dac0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
2dad0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
2dae0 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
2daf0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
2db00 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2db10 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2db20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
2db30 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
2db40 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
2db50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2db60 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
2db70 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
2db80 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
2db90 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
2dba0 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
2dbb0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2dbc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2dbd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2dbe0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2dbf0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2dc00 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2dc10 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2dc20 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2dc30 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2dc40 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20   ^Registering a 
2dc50 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
2dc60 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
2dc70 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ack..**.** ^When
2dc80 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
2dc90 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2dca0 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  e returns zero, 
2dcb0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  the [COMMIT].** 
2dcc0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c  operation is all
2dcd0 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65  owed to continue
2dce0 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20   normally.  ^If 
2dcf0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a  the commit hook.
2dd00 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ** returns non-z
2dd10 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43  ero, then the [C
2dd20 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72  OMMIT] is conver
2dd30 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c  ted into a [ROLL
2dd40 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  BACK]..** ^The r
2dd50 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
2dd60 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
2dd70 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
2dd80 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
2dd90 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
2dda0 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
2ddb0 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
2ddc0 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
2ddd0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2dde0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
2ddf0 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
2de00 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2de10 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
2de20 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
2de30 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
2de40 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
2de50 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
2de60 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
2de70 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
2de80 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
2de90 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
2dea0 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  cur..** ^The rol
2deb0 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
2dec0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
2ded0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2dee0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2def0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
2df00 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
2df10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2df20 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
2df30 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
2df40 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2df50 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  k()] interface..
2df60 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2df70 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
2df80 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
2df90 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
2dfa0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
2dfb0 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
2dfc0 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
2dfd0 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
2dfe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2dff0 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
2e000 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
2e010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e020 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2e030 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2e040 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2e050 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74   function.** wit
2e060 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2e070 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e  connection] iden
2e080 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  tified by the fi
2e090 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
2e0a0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2e0b0 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
2e0c0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2e0d0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2e0e0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
2e0f0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2e100 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
2e110 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68  nction.** for th
2e120 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2e130 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
2e140 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
2e150 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2e160 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2e170 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
2e180 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
2e190 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
2e1a0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2e1b0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54  r deleted..** ^T
2e1c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2e1d0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
2e1e0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
2e1f0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2e200 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
2e210 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
2e220 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61  * ^The second ca
2e230 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
2e240 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2e250 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
2e260 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f  TE_DELETE],.** o
2e270 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
2e280 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ], depending on 
2e290 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
2e2a0 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
2e2b0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20  llback.** to be 
2e2c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
2e2d0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
2e2e0 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
2e2f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
2e300 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ain pointers to 
2e310 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2e320 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  and table name c
2e330 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
2e340 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e  fected row..** ^
2e350 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
2e360 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
2e370 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
2e380 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74  he row..** ^In t
2e390 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
2e3a0 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
2e3b0 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20  e [rowid] after 
2e3c0 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
2e3d0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28   place..**.** ^(
2e3e0 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
2e3f0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
2e400 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
2e410 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
2e420 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
2e430 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
2e440 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
2e450 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ce).)^.**.** ^In
2e460 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
2e470 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65  lementation, the
2e480 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
2e490 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
2e4a0 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20  hen duplication 
2e4b0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
2e4c0 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a   because of an.*
2e4d0 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c  * [ON CONFLICT |
2e4e0 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50   ON CONFLICT REP
2e4f0 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e  LACE] clause.  ^
2e500 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74  Nor is the updat
2e510 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65  e hook.** invoke
2e520 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20  d when rows are 
2e530 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68  deleted using th
2e540 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  e [truncate opti
2e550 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  mization]..** Th
2e560 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66  e exceptions def
2e570 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72  ined in this par
2e580 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61  agraph might cha
2e590 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
2e5a0 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
2e5b0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
2e5c0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c  update hook impl
2e5d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
2e5e0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
2e5f0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
2e600 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2e610 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2e620 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64   invoked the upd
2e630 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61  ate hook.  Any a
2e640 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
2e650 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2e660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2e670 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
2e680 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
2e690 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
2e6a0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2e6b0 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
2e6c0 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74  ggered the updat
2e6d0 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  e hook..** Note 
2e6e0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
2e6f0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2e700 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2e710 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
2e720 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
2e730 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
2e740 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
2e750 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
2e760 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
2e770 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
2e780 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ate_hook(D,C,P) 
2e790 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75  function.** retu
2e7a0 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65  rns the P argume
2e7b0 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
2e7c0 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20  ious call.** on 
2e7d0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
2e7e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2e7f0 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
2e800 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2e810 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  on D..**.** See 
2e820 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
2e830 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d  3_commit_hook()]
2e840 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f   and [sqlite3_ro
2e850 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a  llback_hook()].*
2e860 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f  * interfaces..*/
2e870 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
2e880 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
2e890 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
2e8a0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
2e8b0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
2e8c0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
2e8d0 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
2e8e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2e8f0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
2e900 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
2e910 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59  ger Cache.** KEY
2e920 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63  WORDS: {shared c
2e930 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ache}.**.** ^(Th
2e940 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
2e950 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
2e960 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
2e970 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
2e980 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
2e990 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
2e9a0 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65  etween [database
2e9b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f   connection | co
2e9c0 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f  nnections].** to
2e9d0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2e9e0 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65  se. Sharing is e
2e9f0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
2ea00 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a  gument is true.*
2ea10 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  * and disabled i
2ea20 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
2ea30 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  s false.)^.**.**
2ea40 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20   ^Cache sharing 
2ea50 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
2ea60 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
2ea70 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
2ea80 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
2ea90 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
2eaa0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
2eab0 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
2eac0 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
2ead0 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
2eae0 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
2eaf0 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
2eb00 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2eb10 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61   ^(The cache sha
2eb20 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
2eb30 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2eb40 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
2eb50 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2eb60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
2eb70 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2eb80 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
2eb90 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2eba0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
2ebb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ebc0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
2ebd0 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
2ebe0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
2ebf0 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
2ec00 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
2ec10 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ned.)^.**.** ^(T
2ec20 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2ec30 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2ec40 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
2ec50 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
2ec60 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65  isabled.** succe
2ec70 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
2ec80 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2ec90 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
2eca0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64  )^.**.** ^Shared
2ecb0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
2ecc0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
2ecd0 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
2ece0 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
2ecf0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
2ed00 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
2ed10 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
2ed20 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
2ed30 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
2ed40 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
2ed50 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  itly..**.** See 
2ed60 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53  Also:  [SQLite S
2ed70 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65  hared-Cache Mode
2ed80 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2ed90 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
2eda0 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
2edb0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65  * CAPI3REF: Atte
2edc0 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
2edd0 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54   Memory.**.** ^T
2ede0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
2edf0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
2ee00 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2ee10 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
2ee20 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
2ee30 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
2ee40 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
2ee50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2ee60 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
2ee70 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
2ee80 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  y.   Memory used
2ee90 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
2eea0 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69  se.** pages to i
2eeb0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
2eec0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
2eed0 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61   of non-essentia
2eee0 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71  l memory..** ^sq
2eef0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2ef00 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74  mory() returns t
2ef10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2ef20 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
2ef30 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68  d,.** which migh
2ef40 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
2ef50 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e  s than the amoun
2ef60 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a  t requested..*/.
2ef70 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  int sqlite3_rele
2ef80 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b  ase_memory(int);
2ef90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2efa0 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74  : Impose A Limit
2efb0 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a   On Heap Size.**
2efc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2efd0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
2efe0 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61  () interface pla
2eff0 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d  ces a "soft" lim
2f000 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f  it.** on the amo
2f010 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
2f020 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
2f030 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
2f040 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 69 6e  te..** ^If an in
2f050 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f  ternal allocatio
2f060 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 74  n is requested t
2f070 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64  hat would exceed
2f080 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61   the.** soft hea
2f090 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65  p limit, [sqlite
2f0a0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2f0b0 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ()] is invoked o
2f0c0 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69  ne or.** more ti
2f0d0 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73  mes to free up s
2f0e0 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65  ome space before
2f0f0 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20   the allocation 
2f100 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a  is performed..**
2f110 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69 74 20 69  .** ^The limit i
2f120 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 20  s called "soft" 
2f130 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69  because if [sqli
2f140 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2f150 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20  ry()].** cannot 
2f160 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20  free sufficient 
2f170 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e  memory to preven
2f180 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d  t the limit from
2f190 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c   being exceeded,
2f1a0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69  .** the memory i
2f1b0 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77  s allocated anyw
2f1c0 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65  ay and the curre
2f1d0 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  nt operation pro
2f1e0 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  ceeds..**.** ^A 
2f1f0 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f  negative or zero
2f200 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61   value for N mea
2f210 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73  ns that there is
2f220 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69   no soft heap li
2f230 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  mit and.** [sqli
2f240 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2f250 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20  ry()] will only 
2f260 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d  be called when m
2f270 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74  emory is exhaust
2f280 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  ed..** ^The defa
2f290 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
2f2a0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2f2b0 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t is zero..**.**
2f2c0 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b 65 73 20   ^(SQLite makes 
2f2d0 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f  a best effort to
2f2e0 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20   honor the soft 
2f2f0 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42  heap limit..** B
2f300 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68  ut if the soft h
2f310 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74  eap limit cannot
2f320 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65   be honored, exe
2f330 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63  cution will.** c
2f340 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20  ontinue without 
2f350 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63  error or notific
2f360 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69 73 20 69  ation.)^  This i
2f370 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20  s why the limit 
2f380 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22  is.** called a "
2f390 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74  soft" limit.  It
2f3a0 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c   is advisory onl
2f3b0 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  y..**.** Prior t
2f3c0 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
2f3d0 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75   3.5.0, this rou
2f3e0 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72  tine only constr
2f3f0 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79  ained the memory
2f400 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  .** allocated by
2f410 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
2f420 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65   - the same thre
2f430 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73  ad in which this
2f440 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73   routine.** runs
2f450 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74  .  Beginning wit
2f460 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  h SQLite version
2f470 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74   3.5.0, the soft
2f480 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a   heap limit is.*
2f490 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c  * applied to all
2f4a0 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61   threads. The va
2f4b0 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f  lue specified fo
2f4c0 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
2f4d0 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75  limit.** is an u
2f4e0 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68  pper bound on th
2f4f0 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61  e total memory a
2f500 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c  llocation for al
2f510 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a  l threads. In.**
2f520 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74   version 3.5.0 t
2f530 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61  here is no mecha
2f540 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e  nism for limitin
2f550 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65  g the heap usage
2f560 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75   for.** individu
2f570 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  al threads..*/.v
2f580 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  oid sqlite3_soft
2f590 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29  _heap_limit(int)
2f5a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f5b0 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  F: Extract Metad
2f5c0 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
2f5d0 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a  mn Of A Table.**
2f5e0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2f5f0 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
2f600 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
2f610 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
2f620 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
2f630 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
2f640 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
2f650 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2f660 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2f670 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
2f680 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
2f690 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
2f6a0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
2f6b0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
2f6c0 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
2f6d0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2f6e0 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e  s to.** this fun
2f6f0 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f  ction. ^The seco
2f700 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2f710 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
2f720 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2f730 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
2f740 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61   "temp", or an a
2f750 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2f760 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
2f770 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61   specified.** ta
2f780 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66  ble or NULL. ^If
2f790 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
2f7a0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
2f7b0 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
2f7c0 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
2f7d0 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
2f7e0 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
2f7f0 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61  used by the data
2f800 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a  base engine to.*
2f810 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
2f820 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
2f830 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rences..**.** ^T
2f840 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
2f850 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
2f860 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
2f870 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
2f880 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65  d column.** name
2f890 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
2f8a0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
2f8b0 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
2f8c0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
2f8d0 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  s.** may be NULL
2f8e0 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74  ..**.** ^Metadat
2f8f0 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  a is returned by
2f900 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
2f910 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
2f920 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35   passed as the 5
2f930 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71  th.** and subseq
2f940 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
2f950 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2f960 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20  . ^Any of these 
2f970 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
2f980 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69  .** NULL, in whi
2f990 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72  ch case the corr
2f9a0 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e  esponding elemen
2f9b0 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73  t of metadata is
2f9c0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
2f9d0 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ^(<blockquote>.*
2f9e0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2f9f0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2fa00 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20   Parameter <th> 
2fa10 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c  Output<br>Type <
2fa20 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e  th>  Description
2fa30 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2fa40 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  5th <td> const c
2fa50 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74  har* <td> Data t
2fa60 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ype.** <tr><td> 
2fa70 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  6th <td> const c
2fa80 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f  har* <td> Name o
2fa90 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  f default collat
2faa0 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20  ion sequence.** 
2fab0 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64  <tr><td> 7th <td
2fac0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2fad0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2fae0 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
2faf0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c   constraint.** <
2fb00 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e  tr><td> 8th <td>
2fb10 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
2fb20 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
2fb30 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
2fb40 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c  PRIMARY KEY.** <
2fb50 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e  tr><td> 9th <td>
2fb60 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
2fb70 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
2fb80 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45   is [AUTOINCREME
2fb90 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  NT].** </table>.
2fba0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
2fbb0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  )^.**.** ^The me
2fbc0 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
2fbd0 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
2fbe0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2fbf0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65  ed for the.** de
2fc00 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
2fc10 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
2fc20 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
2fc30 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
2fc40 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  xt.** call to an
2fc50 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e  y SQLite API fun
2fc60 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ction..**.** ^If
2fc70 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74   the specified t
2fc80 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79  able is actually
2fc90 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72   a view, an [err
2fca0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
2fcb0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  rned..**.** ^If 
2fcc0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
2fcd0 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
2fce0 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
2fcf0 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49  d_" and an.** [I
2fd00 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
2fd10 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62  EY] column has b
2fd20 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64  een explicitly d
2fd30 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68  eclared, then th
2fd40 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
2fd50 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
2fd60 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
2fd70 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
2fd80 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73  n. ^(If there is
2fd90 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
2fda0 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
2fdb0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
2fdc0 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
2fdd0 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
2fde0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
2fdf0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
2fe00 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
2fe10 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
2fe20 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
2fe30 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
2fe40 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
2fe50 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
2fe60 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
2fe70 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
2fe80 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
2fe90 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  e>)^.**.** ^(Thi
2fea0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
2feb0 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
2fec0 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
2fed0 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
2fee0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
2fef0 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
2ff00 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
2ff10 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
2ff20 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
2ff30 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
2ff40 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
2ff50 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
2ff60 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
2ff70 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20   left.** in the 
2ff80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ff90 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74  tion] (to be ret
2ffa0 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
2ffb0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29  ite3_errmsg()).)
2ffc0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50  ^.**.** ^This AP
2ffd0 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
2ffe0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2fff0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
30000 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
30010 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
30020 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
30030 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
30040 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  l defined..*/.in
30050 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  t sqlite3_table_
30060 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
30070 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
30080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
30090 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  * Connection han
300a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
300b0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
300c0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
300d0 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f   name or NULL */
300e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
300f0 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f  TableName,     /
30100 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a  * Table name */.
30110 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
30120 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a  olumnName,    /*
30130 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a   Column name */.
30140 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
30150 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a  zDataType,    /*
30160 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65   OUTPUT: Declare
30170 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20  d data type */. 
30180 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
30190 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20  CollSeq,     /* 
301a0 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f  OUTPUT: Collatio
301b0 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  n sequence name 
301c0 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75  */.  int *pNotNu
301d0 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ll,             
301e0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
301f0 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e   if NOT NULL con
30200 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a  straint exists *
30210 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72  /.  int *pPrimar
30220 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20  yKey,           
30230 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
30240 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f  if column part o
30250 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  f PK */.  int *p
30260 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20  Autoinc         
30270 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
30280 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
30290 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e  is auto-incremen
302a0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
302b0 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e  API3REF: Load An
302c0 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a   Extension.**.**
302d0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
302e0 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65   loads an SQLite
302f0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
30300 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65  ry from the name
30310 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d file..**.** ^T
30320 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
30330 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
30340 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
30350 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c  o load an.** SQL
30360 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
30370 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
30380 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c  in the file zFil
30390 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e  e..**.** ^The en
303a0 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
303b0 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61  oc..** ^zProc ma
303c0 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68  y be 0, in which
303d0 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
303e0 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
303f0 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f  t.** defaults to
30400 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
30410 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54  ion_init"..** ^T
30420 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
30430 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
30440 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
30450 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
30460 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
30470 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
30480 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
30490 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  ng..** ^If an er
304a0 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70  ror occurs and p
304b0 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30  zErrMsg is not 0
304c0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73  , then the.** [s
304d0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
304e0 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
304f0 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74  ce shall attempt
30500 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45   to.** fill *pzE
30510 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72  rrMsg with error
30520 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74   message text st
30530 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ored in memory.*
30540 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
30550 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
30560 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  )]. The calling 
30570 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  function.** shou
30580 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
30590 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ory by calling [
305a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
305b0 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
305c0 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
305d0 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a  e enabled using.
305e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ** [sqlite3_enab
305f0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
30600 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61  n()] prior to ca
30610 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a  lling this API,.
30620 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
30630 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
30640 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  turned..**.** Se
30650 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64  e also the [load
30660 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c  _extension() SQL
30670 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69   function]..*/.i
30680 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
30690 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
306a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
306b0 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
306c0 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
306d0 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
306e0 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
306f0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
30700 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
30710 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
30720 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
30730 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
30740 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
30750 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
30760 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
30770 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
30780 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
30790 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
307a0 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
307b0 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
307c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
307d0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
307e0 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
307f0 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e  g.**.** ^So as n
30800 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72  ot to open secur
30810 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64  ity holes in old
30820 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  er applications 
30830 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72  that are.** unpr
30840 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77  epared to deal w
30850 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  ith extension lo
30860 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20  ading, and as a 
30870 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69  means of disabli
30880 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20  ng.** extension 
30890 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76  loading while ev
308a0 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e  aluating user-en
308b0 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66  tered SQL, the f
308c0 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
308d0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74  is provided to t
308e0 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
308f0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
30900 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20  )] mechanism on 
30910 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e  and off..**.** ^
30920 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
30930 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
30940 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20  ult. See ticket 
30950 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20  #1863..** ^Call 
30960 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  the sqlite3_enab
30970 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
30980 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68  n() routine with
30990 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20   onoff==1.** to 
309a0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
309b0 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
309c0 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
309d0 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69  ==0 to turn.** i
309e0 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e  t back off again
309f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30a00 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
30a10 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
30a20 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
30a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30a40 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
30a50 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
30a60 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50  s.**.** ^This AP
30a70 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64  I can be invoked
30a80 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72   at program star
30a90 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  tup in order to 
30aa0 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20  register.** one 
30ab0 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c  or more statical
30ac0 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73  ly linked extens
30ad0 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ions that will b
30ae0 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74  e available.** t
30af0 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62  o all new [datab
30b00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
30b10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
30b20 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20  outine stores a 
30b30 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65  pointer to the e
30b40 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70  xtension entry p
30b50 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  oint.** in an ar
30b60 72 61 79 20 74 68 61 74 20 69 73 20 6f 62 74 61  ray that is obta
30b70 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
30b80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
30b90 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73  hat memory.** is
30ba0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 20   deallocated by 
30bb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61  [sqlite3_reset_a
30bc0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
30bd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  .)^.**.** ^This 
30be0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
30bf0 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20  rs an extension 
30c00 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74  entry point that
30c10 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
30c20 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 65  ally invoked whe
30c30 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61 74  never a new [dat
30c40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30c50 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65 64 20 75  ].** is opened u
30c60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  sing [sqlite3_op
30c70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
30c80 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72  open16()],.** or
30c90 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
30ca0 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70 6c 69 63  2()]..** ^Duplic
30cb0 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  ate extensions a
30cc0 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63  re detected so c
30cd0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
30ce0 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20  ine.** multiple 
30cf0 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
30d00 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73  ame extension is
30d10 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 20 5e 41   harmless..** ^A
30d20 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
30d30 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73  ons apply across
30d40 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
30d50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74  .int sqlite3_aut
30d60 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64  o_extension(void
30d70 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28   (*xEntryPoint)(
30d80 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void));../*.** C
30d90 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
30da0 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69  utomatic Extensi
30db0 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a  on Loading.**.**
30dc0 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
30dd0 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72   disables all pr
30de0 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
30df0 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  red automatic.**
30e00 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 49 74 20   extensions. It 
30e10 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
30e20 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a  t of all prior.*
30e30 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  * [sqlite3_auto_
30e40 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c  extension()] cal
30e50 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ls.)^.**.** ^Thi
30e60 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  s function disab
30e70 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65 78  les automatic ex
30e80 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20  tensions in all 
30e90 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64  threads..*/.void
30ea0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
30eb0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
30ec0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  id);../*.** The 
30ed0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
30ee0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
30ef0 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72  echanism is curr
30f00 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
30f10 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
30f20 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
30f30 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
30f40 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
30f50 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
30f60 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
30f70 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
30f80 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
30f90 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
30fa0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
30fb0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
30fc0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
30fd0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
30fe0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
30ff0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
31000 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
31010 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
31020 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
31030 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75  /../*.** Structu
31040 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20  res used by the 
31050 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
31060 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64  terface.*/.typed
31070 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
31080 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76  3_vtab sqlite3_v
31090 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72  tab;.typedef str
310a0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
310b0 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69  x_info sqlite3_i
310c0 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64  ndex_info;.typed
310d0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
310e0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71  3_vtab_cursor sq
310f0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
31100 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  r;.typedef struc
31110 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
31120 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b   sqlite3_module;
31130 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31140 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
31150 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
31160 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
31170 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  le {virtual tabl
31180 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20  e module}.**.** 
31190 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20  This structure, 
311a0 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64  sometimes called
311b0 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61   a a "virtual ta
311c0 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a  ble module", .**
311d0 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70   defines the imp
311e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
311f0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
31200 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72  ].  .** This str
31210 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20  ucture consists 
31220 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64  mostly of method
31230 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
31240 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75  ..**.** ^A virtu
31250 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20  al table module 
31260 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69  is created by fi
31270 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69  lling in a persi
31280 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63  stent.** instanc
31290 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
312a0 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20  ure and passing 
312b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
312c0 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f  t instance.** to
312d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
312e0 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73  _module()] or [s
312f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
31300 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e  dule_v2()]..** ^
31310 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e  The registration
31320 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75   remains valid u
31330 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61  ntil it is repla
31340 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65  ced by a differe
31350 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20  nt.** module or 
31360 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62  until the [datab
31370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
31380 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e  closes.  The con
31390 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20  tent.** of this 
313a0 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e  structure must n
313b0 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20  ot change while 
313c0 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64  it is registered
313d0 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74   with.** any dat
313e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
313f0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
31400 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69  te3_module {.  i
31410 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
31420 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71  nt (*xCreate)(sq
31430 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
31440 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
31450 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
31460 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
31470 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
31480 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
31490 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
314a0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e  *);.  int (*xCon
314b0 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20  nect)(sqlite3*, 
314c0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
314d0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
314e0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
314f0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
31500 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
31510 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
31520 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
31530 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28  t (*xBestIndex)(
31540 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
31550 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64  Tab, sqlite3_ind
31560 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74  ex_info*);.  int
31570 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28   (*xDisconnect)(
31580 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
31590 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  Tab);.  int (*xD
315a0 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f  estroy)(sqlite3_
315b0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
315c0 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
315d0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
315e0 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  , sqlite3_vtab_c
315f0 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72  ursor **ppCursor
31600 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  );.  int (*xClos
31610 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e)(sqlite3_vtab_
31620 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
31630 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74  (*xFilter)(sqlit
31640 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
31650 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e   int idxNum, con
31660 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c  st char *idxStr,
31670 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
31680 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74   int argc, sqlit
31690 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29  e3_value **argv)
316a0 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29  ;.  int (*xNext)
316b0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
316c0 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
316d0 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74  xEof)(sqlite3_vt
316e0 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
316f0 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71  nt (*xColumn)(sq
31700 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
31710 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r*, sqlite3_cont
31720 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ext*, int);.  in
31730 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69  t (*xRowid)(sqli
31740 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
31750 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
31760 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20  *pRowid);.  int 
31770 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74  (*xUpdate)(sqlit
31780 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20  e3_vtab *, int, 
31790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
317a0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
317b0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67  *);.  int (*xBeg
317c0 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  in)(sqlite3_vtab
317d0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
317e0 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
317f0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
31800 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28   int (*xCommit)(
31810 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
31820 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  Tab);.  int (*xR
31830 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33  ollback)(sqlite3
31840 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
31850 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63   int (*xFindFunc
31860 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  tion)(sqlite3_vt
31870 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e  ab *pVtab, int n
31880 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Arg, const char 
31890 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20  *zName,.        
318a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
318b0 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73  oid (**pxFunc)(s
318c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
318d0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
318e0 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20  e**),.          
318f0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
31900 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e  d **ppArg);.  in
31910 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c  t (*xRename)(sql
31920 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
31930 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
31940 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ew);.};../*.** C
31950 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
31960 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20   Table Indexing 
31970 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b  Information.** K
31980 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
31990 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a  _index_info.**.*
319a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
319b0 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75  dex_info structu
319c0 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74  re and its subst
319d0 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64  ructures is used
319e0 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
319f0 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
31a00 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
31a10 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65  ly from the [xBe
31a20 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68  stIndex].** meth
31a30 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c  od of a [virtual
31a40 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
31a50 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
31a60 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
31a70 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
31a80 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
31a90 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
31aa0 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
31ab0 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
31ac0 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
31ad0 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
31ae0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e  **.** ^(The aCon
31af0 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
31b00 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
31b10 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
31b20 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a   of the form:.**
31b30 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20  .** <pre>column 
31b40 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a  OP expr</pre>.**
31b50 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20  .** where OP is 
31b60 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20  =, &lt;, &lt;=, 
31b70 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29  &gt;, or &gt;=.)
31b80 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63 75  ^  ^(The particu
31b90 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a  lar operator is.
31ba0 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f  ** stored in aCo
31bb0 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 29 5e  nstraint[].op.)^
31bc0 20 20 5e 28 54 68 65 20 69 6e 64 65 78 20 6f 66    ^(The index of
31bd0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73   the column is s
31be0 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e  tored in.** aCon
31bf0 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d  straint[].iColum
31c00 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61  n.)^  ^(aConstra
31c10 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
31c20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
31c30 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
31c40 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
31c50 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
31c60 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
31c70 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
31c80 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
31c90 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a  it cannot.)^.**.
31ca0 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65  ** ^The optimize
31cb0 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  r automatically 
31cc0 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66  inverts terms of
31cd0 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20   the form "expr 
31ce0 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e  OP column".** an
31cf0 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69  d makes other si
31d00 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f  mplifications to
31d10 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
31d20 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  e in an attempt 
31d30 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e  to.** get as man
31d40 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  y WHERE clause t
31d50 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f  erms into the fo
31d60 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61  rm shown above a
31d70 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e  s possible..** ^
31d80 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
31d90 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70  ] array only rep
31da0 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73  orts WHERE claus
31db0 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 72 65  e terms that are
31dc0 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f 20  .** relevant to 
31dd0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76  the particular v
31de0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69  irtual table bei
31df0 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a  ng queried..**.*
31e00 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  * ^Information a
31e10 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42  bout the ORDER B
31e20 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72  Y clause is stor
31e30 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d  ed in aOrderBy[]
31e40 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20  ..** ^Each term 
31e50 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f  of aOrderBy reco
31e60 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  rds a column of 
31e70 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
31e80 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  use..**.** The [
31e90 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68  xBestIndex] meth
31ea0 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f  od must fill aCo
31eb0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
31ec0 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  with information
31ed0 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70  .** about what p
31ee0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73  arameters to pas
31ef0 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e  s to xFilter.  ^
31f00 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74  If argvIndex>0 t
31f10 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74  hen.** the right
31f20 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68  -hand side of th
31f30 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
31f40 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73  aConstraint[] is
31f50 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e   evaluated.** an
31f60 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72  d becomes the ar
31f70 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79  gvIndex-th entry
31f80 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20   in argv.  ^(If 
31f90 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
31fa0 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72  [].omit.** is tr
31fb0 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  ue, then the con
31fc0 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d  straint is assum
31fd0 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68  ed to be fully h
31fe0 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  andled by the.**
31ff0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
32000 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65  nd is not checke
32010 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74  d again by SQLit
32020 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e.)^.**.** ^The 
32030 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74  idxNum and idxPt
32040 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63  r values are rec
32050 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64  orded and passed
32060 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46   into the.** [xF
32070 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a  ilter] method..*
32080 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  * ^[sqlite3_free
32090 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66  ()] is used to f
320a0 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 6e  ree idxPtr if an
320b0 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65  d only if.** nee
320c0 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73  dToFreeIdxPtr is
320d0 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   true..**.** ^Th
320e0 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  e orderByConsume
320f0 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74  d means that out
32100 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65  put from [xFilte
32110 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20  r]/[xNext] will 
32120 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20  occur in.** the 
32130 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f  correct order to
32140 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44   satisfy the ORD
32150 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20  ER BY clause so 
32160 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65  that no separate
32170 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70  .** sorting step
32180 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
32190 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74  .** ^The estimat
321a0 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20  edCost value is 
321b0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74  an estimate of t
321c0 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67  he cost of doing
321d0 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c   the.** particul
321e0 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75  ar lookup.  A fu
321f0 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62  ll scan of a tab
32200 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65  le with N entrie
32210 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  s should have.**
32220 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41   a cost of N.  A
32230 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f   binary search o
32240 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65  f a table of N e
32250 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
32260 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20  ve a.** cost of 
32270 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f  approximately lo
32280 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  g(N)..*/.struct 
32290 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
322a0 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73  fo {.  /* Inputs
322b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74   */.  int nConst
322c0 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
322d0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e   /* Number of en
322e0 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72  tries in aConstr
322f0 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74  aint */.  struct
32300 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
32310 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20  onstraint {.    
32320 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
32330 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
32340 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e  lumn on left-han
32350 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72  d side of constr
32360 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73  aint */.     uns
32370 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20  igned char op;  
32380 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72         /* Constr
32390 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f  aint operator */
323a0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
323b0 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20  har usable;     
323c0 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20  /* True if this 
323d0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73  constraint is us
323e0 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74  able */.     int
323f0 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20   iTermOffset;   
32400 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
32410 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73  nternally - xBes
32420 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67  tIndex should ig
32430 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  nore */.  } *aCo
32440 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
32450 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66       /* Table of
32460 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
32470 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69  nstraints */.  i
32480 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20  nt nOrderBy;    
32490 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
324a0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
324b0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
324c0 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  use */.  struct 
324d0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72  sqlite3_index_or
324e0 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74  derby {.     int
324f0 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
32500 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
32510 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20   number */.     
32520 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65  unsigned char de
32530 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  sc;       /* Tru
32540 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c  e for DESC.  Fal
32550 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20  se for ASC. */. 
32560 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20   } *aOrderBy;   
32570 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
32580 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
32590 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75  se */.  /* Outpu
325a0 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  ts */.  struct s
325b0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
325c0 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a  straint_usage {.
325d0 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
325e0 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
325f0 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e  if >0, constrain
32600 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67  t is part of arg
32610 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a  v to xFilter */.
32620 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
32630 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20  r omit;      /* 
32640 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65  Do not code a te
32650 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73  st for this cons
32660 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61  traint */.  } *a
32670 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b  ConstraintUsage;
32680 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20  .  int idxNum;  
32690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
326a0 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20   Number used to 
326b0 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64  identify the ind
326c0 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64  ex */.  char *id
326d0 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20  xStr;           
326e0 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f     /* String, po
326f0 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20  ssibly obtained 
32700 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
32710 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65  loc */.  int nee
32720 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20  dToFreeIdxStr;  
32730 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53      /* Free idxS
32740 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  tr using sqlite3
32750 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20  _free() if true 
32760 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79  */.  int orderBy
32770 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20  Consumed;       
32780 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75  /* True if outpu
32790 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64  t is already ord
327a0 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65  ered */.  double
327b0 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20   estimatedCost; 
327c0 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65       /* Estimate
327d0 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20  d cost of using 
327e0 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b  this index */.};
327f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
32800 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
32810 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65  _EQ    2.#define
32820 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
32830 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34  NSTRAINT_GT    4
32840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
32850 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
32860 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65  _LE    8.#define
32870 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
32880 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31  NSTRAINT_LT    1
32890 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
328a0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
328b0 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69  T_GE    32.#defi
328c0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
328d0 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48  CONSTRAINT_MATCH
328e0 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   64../*.** CAPI3
328f0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
32900 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d  Virtual Table Im
32910 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a  plementation.**.
32920 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
32930 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 72  es are used to r
32940 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76  egister a new [v
32950 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
32960 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d  ule] name..** ^M
32970 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74  odule names must
32980 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62   be registered b
32990 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e  efore.** creatin
329a0 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c  g a new [virtual
329b0 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68   table] using th
329c0 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65 66  e module and bef
329d0 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70  ore using a.** p
329e0 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74  reexisting [virt
329f0 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74  ual table] for t
32a00 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a  he module..**.**
32a10 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d   ^The module nam
32a20 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  e is registered 
32a30 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
32a40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
32a50 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
32a60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
32a70 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  .  ^The name of 
32a80 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69  the module is gi
32a90 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73  ven by the .** s
32aa0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
32ab0 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
32ac0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
32ad0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d  ter to.** the im
32ae0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32af0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
32b00 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54  le module].   ^T
32b10 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72  he fourth.** par
32b20 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
32b30 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61  itrary client da
32b40 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
32b50 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
32b60 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78  h.** into the [x
32b70 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f  Create] and [xCo
32b80 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f  nnect] methods o
32b90 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
32ba0 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68  ble module.** wh
32bb0 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c  en a new virtual
32bc0 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65 69   table is be bei
32bd0 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72 65  ng created or re
32be0 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a  initialized..**.
32bf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32c00 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
32c10 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61 73  () interface has
32c20 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65 74   a fifth paramet
32c30 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
32c40 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65   pointer to a de
32c50 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
32c60 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e   pClientData.  ^
32c70 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69  SQLite will.** i
32c80 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
32c90 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69  ctor function (i
32ca0 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
32cb0 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  ) when SQLite.**
32cc0 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73   no longer needs
32cd0 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61   the pClientData
32ce0 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
32cf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
32d00 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72  odule().** inter
32d10 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65  face is equivale
32d20 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
32d30 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
32d40 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20   with a NULL.** 
32d50 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69  destructor..*/.i
32d60 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
32d70 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69  e_module(.  sqli
32d80 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
32d90 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
32da0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
32db0 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
32dc0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
32dd0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
32de0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
32df0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
32e00 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
32e10 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
32e20 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
32e30 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
32e40 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20  ClientData      
32e50 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
32e60 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
32e70 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e  Connect */.);.in
32e80 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
32e90 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71  _module_v2(.  sq
32ea0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
32eb0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
32ec0 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
32ed0 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
32ee0 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
32ef0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
32f00 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
32f10 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
32f20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
32f30 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
32f40 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
32f50 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
32f60 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20  *pClientData,   
32f70 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
32f80 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
32f90 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76  /xConnect */.  v
32fa0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
32fb0 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64  oid*)     /* Mod
32fc0 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  ule destructor f
32fd0 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f  unction */.);../
32fe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
32ff0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73  irtual Table Ins
33000 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  tance Object.** 
33010 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
33020 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65  3_vtab.**.** Eve
33030 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ry [virtual tabl
33040 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d  e module] implem
33050 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
33060 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74  subclass.** of t
33070 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65  his object to de
33080 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75  scribe a particu
33090 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  lar instance.** 
330a0 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
330b0 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75  table].  Each su
330c0 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
330d0 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68  e tailored to th
330e0 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
330f0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
33100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
33110 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66  * The purpose of
33120 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   this superclass
33130 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65   is to define ce
33140 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61  rtain fields tha
33150 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20  t are.** common 
33160 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d  to all module im
33170 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
33180 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61  *.** ^Virtual ta
33190 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e  bles methods can
331a0 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65   set an error me
331b0 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69  ssage by assigni
331c0 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  ng a.** string o
331d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
331e0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
331f0 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68   to zErrMsg.  Th
33200 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a  e method should.
33210 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61  ** take care tha
33220 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69  t any prior stri
33230 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61  ng is freed by a
33240 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33250 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69  3_free()].** pri
33260 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
33270 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
33280 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72  zErrMsg.  ^After
33290 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
332a0 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72  ge.** is deliver
332b0 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69  ed up to the cli
332c0 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ent application,
332d0 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
332e0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
332f0 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71  y.** freed by sq
33300 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64  lite3_free() and
33310 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
33320 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65  ld will be zeroe
33330 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  d..*/.struct sql
33340 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f  ite3_vtab {.  co
33350 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
33360 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a  le *pModule;  /*
33370 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20   The module for 
33380 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62  this virtual tab
33390 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  le */.  int nRef
333a0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
333b0 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f          /* NO LO
333c0 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63  NGER USED */.  c
333d0 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20  har *zErrMsg;   
333e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
333f0 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * Error message 
33400 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
33410 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56  intf() */.  /* V
33420 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
33430 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
33440 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
33450 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
33460 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
33470 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
33480 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62   Table Cursor Ob
33490 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
334a0 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  : sqlite3_vtab_c
334b0 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74  ursor {virtual t
334c0 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a  able cursor}.**.
334d0 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
334e0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
334f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
33500 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
33510 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  f the.** followi
33520 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  ng structure to 
33530 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
33540 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
33550 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   the.** [virtual
33560 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20   table] and are 
33570 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
33580 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
33590 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
335a0 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
335b0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
335c0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70  lite3_module.xOp
335d0 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68  en | xOpen] meth
335e0 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
335f0 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79   and are destroy
33600 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71  ed.** by the [sq
33610 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c  lite3_module.xCl
33620 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65  ose | xClose] me
33630 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61  thod.  Cursors a
33640 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  re used.** by th
33650 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e  e [xFilter], [xN
33660 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78  ext], [xEof], [x
33670 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52  Column], and [xR
33680 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a  owid] methods.**
33690 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
336a0 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70   Each module imp
336b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
336c0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63   define.** the c
336d0 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73  ontent of a curs
336e0 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  or structure to 
336f0 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65  suit its own nee
33700 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  ds..**.** This s
33710 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73  uperclass exists
33720 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66   in order to def
33730 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ine fields of th
33740 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a  e cursor that.**
33750 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61   are common to a
33760 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ll implementatio
33770 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ns..*/.struct sq
33780 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
33790 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74  r {.  sqlite3_vt
337a0 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20  ab *pVtab;      
337b0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
337c0 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20   of this cursor 
337d0 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
337e0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
337f0 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
33800 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
33810 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
33820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33830 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63  : Declare The Sc
33840 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61  hema Of A Virtua
33850 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54  l Table.**.** ^T
33860 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64  he [xCreate] and
33870 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68   [xConnect] meth
33880 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72  ods of a.** [vir
33890 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
338a0 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74  e] call this int
338b0 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63  erface.** to dec
338c0 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20  lare the format 
338d0 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64  (the names and d
338e0 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20  atatypes of the 
338f0 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74  columns) of.** t
33900 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
33910 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74  s they implement
33920 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33930 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71  _declare_vtab(sq
33940 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
33950 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a  ar *zSQL);../*.*
33960 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72  * CAPI3REF: Over
33970 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20  load A Function 
33980 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  For A Virtual Ta
33990 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74  ble.**.** ^(Virt
339a0 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70  ual tables can p
339b0 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69  rovide alternati
339c0 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
339d0 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ns of functions.
339e0 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46  ** using the [xF
339f0 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74  indFunction] met
33a00 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74  hod of the [virt
33a10 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
33a20 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62  ].  .** But glob
33a30 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  al versions of t
33a40 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hose functions.*
33a50 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20  * must exist in 
33a60 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72  order to be over
33a70 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  loaded.)^.**.** 
33a80 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73  ^(This API makes
33a90 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76   sure a global v
33aa0 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63  ersion of a func
33ab0 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74  tion with a part
33ac0 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61  icular.** name a
33ad0 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  nd number of par
33ae0 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20  ameters exists. 
33af0 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63   If no such func
33b00 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62  tion exists.** b
33b10 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69  efore this API i
33b20 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20  s called, a new 
33b30 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61  function is crea
33b40 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70  ted.)^  ^The imp
33b50 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
33b60 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
33b70 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
33b80 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
33b90 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
33ba0 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
33bb0 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
33bc0 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
33bd0 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
33be0 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
33bf0 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c  to be a placehol
33c00 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  der function tha
33c10 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61  t can be overloa
33c20 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72  ded.** by a [vir
33c30 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a  tual table]..*/.
33c40 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72  int sqlite3_over
33c50 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71  load_function(sq
33c60 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
33c70 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69  ar *zFuncName, i
33c80 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a  nt nArg);../*.**
33c90 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
33ca0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
33cb0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65  ble mechanism de
33cc0 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63  fined above (bac
33cd0 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d  k up.** to a com
33ce0 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20  ment remarkably 
33cf0 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20  similar to this 
33d00 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c  one) is currentl
33d10 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
33d20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
33d30 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
33d40 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
33d50 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
33d60 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
33d70 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
33d80 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
33d90 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
33da0 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
33db0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
33dc0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
33dd0 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
33de0 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
33df0 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
33e00 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
33e10 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
33e20 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
33e30 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
33e40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
33e50 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70   Handle To An Op
33e60 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f  en BLOB.** KEYWO
33e70 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  RDS: {BLOB handl
33e80 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  e} {BLOB handles
33e90 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
33ea0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
33eb0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
33ec0 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68   open BLOB on wh
33ed0 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
33ee0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
33ef0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
33f00 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  ] can be perform
33f10 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20  ed..** ^Objects 
33f20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72 65  of this type are
33f30 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c   created by [sql
33f40 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
33f50 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79  ].** and destroy
33f60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
33f70 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  lob_close()]..**
33f80 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
33f90 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
33fa0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
33fb0 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
33fc0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
33fd0 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
33fe0 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
33ff0 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ons of the BLOB.
34000 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
34010 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
34020 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34030 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
34040 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e  e BLOB in bytes.
34050 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
34060 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ct sqlite3_blob 
34070 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f  sqlite3_blob;../
34080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
34090 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49  pen A BLOB For I
340a0 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a  ncremental I/O.*
340b0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
340c0 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b  rfaces opens a [
340d0 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61  BLOB handle | ha
340e0 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f  ndle] to the BLO
340f0 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20  B located.** in 
34100 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e  row iRow, column
34110 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20   zColumn, table 
34120 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61  zTable in databa
34130 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74  se zDb;.** in ot
34140 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73  her words, the s
34150 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f  ame BLOB that wo
34160 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20  uld be selected 
34170 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  by:.**.** <pre>.
34180 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43  **     SELECT zC
34190 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a  olumn FROM zDb.z
341a0 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77  Table WHERE [row
341b0 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c  id] = iRow;.** <
341c0 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  /pre>)^.**.** ^I
341d0 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  f the flags para
341e0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72  meter is non-zer
341f0 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42  o, then the BLOB
34200 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
34210 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65  ead.** and write
34220 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74 20   access. ^If it 
34230 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f  is zero, the BLO
34240 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
34250 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20  read access..** 
34260 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69  ^It is not possi
34270 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f  ble to open a co
34280 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72  lumn that is par
34290 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72  t of an index or
342a0 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79   primary .** key
342b0 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49   for writing. ^I
342c0 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  f [foreign key c
342d0 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20  onstraints] are 
342e0 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a  enabled, it is .
342f0 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
34300 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e  to open a column
34310 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66   that is part of
34320 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66   a [child key] f
34330 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a  or writing..**.*
34340 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
34350 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
34360 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61  s not the filena
34370 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  me that contains
34380 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
34390 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20   but rather the 
343a0 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66  symbolic name of
343b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
343c0 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61 66  at.** appears af
343d0 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f  ter the AS keywo
343e0 72 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  rd when the data
343f0 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65  base is connecte
34400 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d  d using [ATTACH]
34410 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61  ..** ^For the ma
34420 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
34430 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  , the database n
34440 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a  ame is "main"..*
34450 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62 6c  * ^For TEMP tabl
34460 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  es, the database
34470 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e   name is "temp".
34480 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63  .**.** ^(On succ
34490 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
344a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
344b0 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68   the new [BLOB h
344c0 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65  andle] is writte
344d0 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e  n.** to *ppBlob.
344e0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
344f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
34500 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c  turned and *ppBl
34510 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  ob is set.** to 
34520 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65  be a null pointe
34530 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75  r.)^.** ^This fu
34540 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20  nction sets the 
34550 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34560 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65  tion] error code
34570 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
34580 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b  accessible via [
34590 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
345a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
345b0 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65  errmsg()] and re
345c0 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  lated.** functio
345d0 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  ns. ^Note that t
345e0 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61  he *ppBlob varia
345f0 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e  ble is always in
34600 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a  itialized in a.*
34610 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  * way that makes
34620 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f   it safe to invo
34630 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ke [sqlite3_blob
34640 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70  _close()] on *pp
34650 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65  Blob.** regardle
34660 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
34670 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  s or failure of 
34680 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
34690 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f 77  .** ^(If the row
346a0 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e   that a BLOB han
346b0 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  dle points to is
346c0 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a   modified by an.
346d0 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45  ** [UPDATE], [DE
346e0 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e  LETE], or by [ON
346f0 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d   CONFLICT] side-
34700 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20  effects.** then 
34710 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  the BLOB handle 
34720 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78  is marked as "ex
34730 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20  pired"..** This 
34740 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63  is true if any c
34750 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77  olumn of the row
34760 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65   is changed, eve
34770 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74  n a column.** ot
34780 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  her than the one
34790 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
347a0 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a   is open on.)^.*
347b0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  * ^Calls to [sql
347c0 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
347d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
347e0 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72  lob_write()] for
347f0 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c  .** a expired BL
34800 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77  OB handle fail w
34810 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f  ith an return co
34820 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
34830 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67  ORT]..** ^(Chang
34840 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  es written into 
34850 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20  a BLOB prior to 
34860 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e  the BLOB expirin
34870 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c  g are not.** rol
34880 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 20  led back by the 
34890 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68  expiration of th
348a0 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68  e BLOB.  Such ch
348b0 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74  anges will event
348c0 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20  ually.** commit 
348d0 69 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  if the transacti
348e0 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  on continues to 
348f0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a  completion.)^.**
34900 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b 73 71  .** ^Use the [sq
34910 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
34920 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
34930 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73   determine the s
34940 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  ize of.** the op
34950 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65  ened blob.  ^The
34960 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20   size of a blob 
34970 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67  may not be chang
34980 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e  ed by this.** in
34990 74 65 72 66 61 63 65 2e 20 20 55 73 65 20 74 68  terface.  Use th
349a0 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63  e [UPDATE] SQL c
349b0 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65  ommand to change
349c0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a   the size of a.*
349d0 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54  * blob..**.** ^T
349e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
349f0 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64  _zeroblob()] and
34a00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
34a10 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74  _zeroblob()] int
34a20 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74  erfaces.** and t
34a30 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72  he built-in [zer
34a40 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74  oblob] SQL funct
34a50 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c  ion can be used,
34a60 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20   if desired,.** 
34a70 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70  to create an emp
34a80 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20  ty, zero-filled 
34a90 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f  blob in which to
34aa0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 75   read or write u
34ab0 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74  sing.** this int
34ac0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f  erface..**.** To
34ad0 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63   avoid a resourc
34ae0 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70  e leak, every op
34af0 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
34b00 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c   should eventual
34b10 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65  ly.** be release
34b20 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b  d by a call to [
34b30 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
34b40 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  se()]..*/.int sq
34b50 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
34b60 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63  .  sqlite3*,.  c
34b70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a  onst char *zDb,.
34b80 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
34b90 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68  able,.  const ch
34ba0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73  ar *zColumn,.  s
34bb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f  qlite3_int64 iRo
34bc0 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a  w,.  int flags,.
34bd0 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a    sqlite3_blob *
34be0 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a  *ppBlob.);../*.*
34bf0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73  * CAPI3REF: Clos
34c00 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a  e A BLOB Handle.
34c10 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73 20 61 6e  **.** ^Closes an
34c20 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
34c30 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73  le]..**.** ^Clos
34c40 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c  ing a BLOB shall
34c50 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65   cause the curre
34c60 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  nt transaction t
34c70 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74  o commit.** if t
34c80 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65  here are no othe
34c90 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64  r BLOBs, no pend
34ca0 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61  ing prepared sta
34cb0 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65  tements, and the
34cc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
34cd0 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61  nection is in [a
34ce0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e  utocommit mode].
34cf0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77 72 69 74  .** ^If any writ
34d00 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20  es were made to 
34d10 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d  the BLOB, they m
34d20 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20  ight be held in 
34d30 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74  cache.** until t
34d40 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69  he close operati
34d50 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20  on if they will 
34d60 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f  fit..**.** ^(Clo
34d70 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66  sing the BLOB of
34d80 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63  ten forces the c
34d90 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f  hanges.** out to
34da0 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20   disk and so if 
34db0 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f  any I/O errors o
34dc0 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20  ccur, they will 
34dd0 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20  likely occur.** 
34de0 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
34df0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f   the BLOB is clo
34e00 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73  sed.  Any errors
34e10 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69   that occur duri
34e20 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72  ng.** closing ar
34e30 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20  e reported as a 
34e40 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20  non-zero return 
34e50 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  value.)^.**.** ^
34e60 28 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f  (The BLOB is clo
34e70 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61  sed unconditiona
34e80 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68  lly.  Even if th
34e90 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
34ea0 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63  ns.** an error c
34eb0 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73  ode, the BLOB is
34ec0 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e   still closed.)^
34ed0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
34ee0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
34ef0 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72  h a null pointer
34f00 20 28 73 75 63 68 20 61 73 20 77 6f 75 6c 64 20   (such as would 
34f10 62 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  be returned.** b
34f20 79 20 61 20 66 61 69 6c 65 64 20 63 61 6c 6c 20  y a failed call 
34f30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
34f40 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20 68  _open()]) is a h
34f50 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
34f60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
34f70 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  ob_close(sqlite3
34f80 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
34f90 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72   CAPI3REF: Retur
34fa0 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e  n The Size Of An
34fb0 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a   Open BLOB.**.**
34fc0 20 5e 52 65 74 75 72 6e 73 20 74 68 65 20 73 69   ^Returns the si
34fd0 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74  ze in bytes of t
34fe0 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62  he BLOB accessib
34ff0 6c 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20 73  le via the .** s
35000 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e  uccessfully open
35010 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
35020 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67   in its only arg
35030 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a 20  ument.  ^The.** 
35040 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62  incremental blob
35050 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63 61   I/O routines ca
35060 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f  n only read or o
35070 76 65 72 77 72 69 74 69 6e 67 20 65 78 69 73 74  verwriting exist
35080 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74  ing.** blob cont
35090 65 6e 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74  ent; they cannot
350a0 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65   change the size
350b0 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a   of a blob..**.*
350c0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
350d0 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
350e0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
350f0 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
35100 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
35110 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
35120 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
35130 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
35140 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
35150 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
35160 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
35170 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
35180 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
35190 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
351a0 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
351b0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
351c0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
351d0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
351e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
351f0 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lob_bytes(sqlite
35200 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a  3_blob *);../*.*
35210 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 61 64  * CAPI3REF: Read
35220 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f   Data From A BLO
35230 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a  B Incrementally.
35240 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
35250 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ction is used to
35260 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20   read data from 
35270 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  an open [BLOB ha
35280 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20  ndle] into a.** 
35290 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20  caller-supplied 
352a0 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20  buffer. N bytes 
352b0 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69  of data are copi
352c0 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a  ed into buffer Z
352d0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  .** from the ope
352e0 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67  n BLOB, starting
352f0 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
35300 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  et.)^.**.** ^If 
35310 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69  offset iOffset i
35320 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79  s less than N by
35330 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64  tes from the end
35340 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a   of the BLOB,.**
35350 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
35360 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
35370 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e  no data is read.
35380 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f 66 66 73    ^If N or iOffs
35390 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68  et is.** less th
353a0 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45  an zero, [SQLITE
353b0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
353c0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
353d0 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e 54 68 65  is read..** ^The
353e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f   size of the blo
353f0 62 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  b (and hence the
35400 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
35410 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
35420 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
35430 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
35440 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
35450 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
35460 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20  .** ^An attempt 
35470 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e 20  to read from an 
35480 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61  expired [BLOB ha
35490 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68  ndle] fails with
354a0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64   an.** error cod
354b0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
354c0 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20  RT]..**.** ^(On 
354d0 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33  success, sqlite3
354e0 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20 72 65 74  _blob_read() ret
354f0 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
35500 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  ** Otherwise, an
35510 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
35520 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72   an [extended er
35530 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
35540 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  urned.)^.**.** T
35550 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
35560 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f   works on a [BLO
35570 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20  B handle] which 
35580 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64  has been created
35590 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73  .** by a prior s
355a0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
355b0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
355c0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63  open()] and whic
355d0 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65  h has not.** bee
355e0 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c  n closed by [sql
355f0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
35600 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79  )].  Passing any
35610 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69   other pointer i
35620 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75  n.** to this rou
35630 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20  tine results in 
35640 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
35650 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
35660 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  le behavior..**.
35670 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
35680 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
35690 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
356a0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71  te3_blob_read(sq
356b0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f  lite3_blob *, vo
356c0 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e  id *Z, int N, in
356d0 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
356e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72 69  ** CAPI3REF: Wri
356f0 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42  te Data Into A B
35700 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c  LOB Incrementall
35710 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
35720 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
35730 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e 74  o write data int
35740 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  o an open [BLOB 
35750 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a  handle] from a.*
35760 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65  * caller-supplie
35770 64 20 62 75 66 66 65 72 2e 20 5e 4e 20 62 79 74  d buffer. ^N byt
35780 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63  es of data are c
35790 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62  opied from the b
357a0 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20  uffer Z.** into 
357b0 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73  the open BLOB, s
357c0 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
357d0 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a  t iOffset..**.**
357e0 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68   ^If the [BLOB h
357f0 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73  andle] passed as
35800 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
35810 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e  ent was not open
35820 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e  ed for.** writin
35830 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72  g (the flags par
35840 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
35850 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
35860 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68  was zero),.** th
35870 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
35880 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  rns [SQLITE_READ
35890 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ONLY]..**.** ^Th
358a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
358b0 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  only modify the 
358c0 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20  contents of the 
358d0 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e  BLOB; it is.** n
358e0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69  ot possible to i
358f0 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65  ncrease the size
35900 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 6e 67   of a BLOB using
35910 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 5e 49   this API..** ^I
35920 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  f offset iOffset
35930 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20   is less than N 
35940 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65  bytes from the e
35950 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a  nd of the BLOB,.
35960 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
35970 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
35980 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
35990 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20 69 73 0a  tten.  ^If N is.
359a0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  ** less than zer
359b0 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  o [SQLITE_ERROR]
359c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
359d0 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74   no data is writ
359e0 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65  ten..** The size
359f0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61 6e   of the BLOB (an
35a00 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69  d hence the maxi
35a10 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69  mum value of N+i
35a20 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62  Offset).** can b
35a30 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
35a40 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
35a50 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
35a60 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
35a70 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72  An attempt to wr
35a80 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65  ite to an expire
35a90 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  d [BLOB handle] 
35aa0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a  fails with an.**
35ab0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
35ac0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20  SQLITE_ABORT].  
35ad0 5e 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42  ^Writes to the B
35ae0 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65  LOB that occurre
35af0 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  d.** before the 
35b00 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78  [BLOB handle] ex
35b10 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f  pired are not ro
35b20 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65  lled back by the
35b30 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f  .** expiration o
35b40 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68  f the handle, th
35b50 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
35b60 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67  hose changes mig
35b70 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20  ht.** have been 
35b80 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
35b90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
35ba0 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c  t expired the BL
35bb0 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20  OB handle.** or 
35bc0 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e  by other indepen
35bd0 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e  dent statements.
35be0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63  .**.** ^(On succ
35bf0 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ess, sqlite3_blo
35c00 62 5f 77 72 69 74 65 28 29 20 72 65 74 75 72 6e  b_write() return
35c10 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20  s SQLITE_OK..** 
35c20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20 5b  Otherwise, an  [
35c30 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61  error code] or a
35c40 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  n [extended erro
35c50 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
35c60 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69  ned.)^.**.** Thi
35c70 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77  s routine only w
35c80 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20  orks on a [BLOB 
35c90 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61  handle] which ha
35ca0 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a  s been created.*
35cb0 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63  * by a prior suc
35cc0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
35cd0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
35ce0 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20  en()] and which 
35cf0 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20  has not.** been 
35d00 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  closed by [sqlit
35d10 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
35d20 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f  .  Passing any o
35d30 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a  ther pointer in.
35d40 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ** to this routi
35d50 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ne results in un
35d60 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
35d70 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
35d80 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
35d90 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
35da0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
35db0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35dc0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69  _blob_write(sqli
35dd0 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73  te3_blob *, cons
35de0 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e  t void *z, int n
35df0 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
35e00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35e10 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79   Virtual File Sy
35e20 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a  stem Objects.**.
35e30 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c  ** A virtual fil
35e40 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 73  esystem (VFS) is
35e50 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
35e60 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74  ] object.** that
35e70 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20   SQLite uses to 
35e80 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68  interact.** with
35e90 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
35ea0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
35eb0 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 62  .  Most SQLite b
35ec0 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20  uilds come with 
35ed0 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61  a.** single defa
35ee0 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73 20  ult VFS that is 
35ef0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
35f00 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65  the host compute
35f10 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20  r..** New VFSes 
35f20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
35f30 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56  d and existing V
35f40 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65  FSes can be unre
35f50 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65  gistered..** The
35f60 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72   following inter
35f70 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
35f80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
35f90 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
35fa0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35fb0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
35fc0 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73   a VFS given its
35fd0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73   name..** ^Names
35fe0 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74   are case sensit
35ff0 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61  ive..** ^Names a
36000 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
36010 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
36020 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72 65 20 69  ..** ^If there i
36030 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55  s no match, a NU
36040 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
36050 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 7a  turned..** ^If z
36060 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20  VfsName is NULL 
36070 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
36080 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 64   VFS is returned
36090 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20 56 46 53  ..**.** ^New VFS
360a0 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  es are registere
360b0 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76  d with sqlite3_v
360c0 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a  fs_register()..*
360d0 2a 20 5e 45 61 63 68 20 6e 65 77 20 56 46 53 20  * ^Each new VFS 
360e0 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
360f0 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
36100 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
36110 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 61 6d  set..** ^The sam
36120 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67  e VFS can be reg
36130 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
36140 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69   times without i
36150 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f 20 6d 61  njury..** ^To ma
36160 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56  ke an existing V
36170 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61  FS into the defa
36180 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65  ult VFS, registe
36190 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69  r it again.** wi
361a0 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20  th the makeDflt 
361b0 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77  flag set.  If tw
361c0 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65  o different VFSe
361d0 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61  s with the.** sa
361e0 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69  me name are regi
361f0 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61  stered, the beha
36200 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
36210 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20  d.  If a.** VFS 
36220 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
36230 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69  th a name that i
36240 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70  s NULL or an emp
36250 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68  ty string,.** th
36260 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
36270 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
36280 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74 65 72 20  .** ^Unregister 
36290 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20 73  a VFS with the s
362a0 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
362b0 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61 63  ister() interfac
362c0 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 64  e..** ^(If the d
362d0 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e  efault VFS is un
362e0 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74  registered, anot
362f0 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65  her VFS is chose
36300 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61  n as.** the defa
36310 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65  ult.  The choice
36320 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53   for the new VFS
36330 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 29 5e   is arbitrary.)^
36340 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20  .*/.sqlite3_vfs 
36350 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  *sqlite3_vfs_fin
36360 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56  d(const char *zV
36370 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c  fsName);.int sql
36380 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
36390 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  r(sqlite3_vfs*, 
363a0 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69  int makeDflt);.i
363b0 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  nt sqlite3_vfs_u
363c0 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  nregister(sqlite
363d0 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  3_vfs*);../*.** 
363e0 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65  CAPI3REF: Mutexe
363f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  s.**.** The SQLi
36400 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
36410 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  se routines for 
36420 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72  thread.** synchr
36430 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67  onization. Thoug
36440 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e  h they are inten
36450 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c  ded for internal
36460 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74  .** use by SQLit
36470 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e  e, code that lin
36480 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74  ks against SQLit
36490 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65  e is.** permitte
364a0 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20  d to use any of 
364b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
364c0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
364d0 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e   source code con
364e0 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69  tains multiple i
364f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
36500 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78  * of these mutex
36510 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61   routines.  An a
36520 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65  ppropriate imple
36530 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
36540 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74  selected automat
36550 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c  ically at compil
36560 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68 65 20 66  e-time.  ^(The f
36570 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c  ollowing.** impl
36580 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20  ementations are 
36590 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
365a0 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a   SQLite core:.**
365b0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
365c0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
365d0 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  OS2.** <li>   SQ
365e0 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
365f0 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  AD.** <li>   SQL
36600 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a  ITE_MUTEX_W32.**
36610 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
36620 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75  UTEX_NOOP.** </u
36630 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  l>)^.**.** ^The 
36640 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f  SQLITE_MUTEX_NOO
36650 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  P implementation
36660 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75   is a set of rou
36670 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f  tines.** that do
36680 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69  es no real locki
36690 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70  ng and is approp
366a0 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e  riate for use in
366b0 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72  .** a single-thr
366c0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
366d0 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  n.  ^The SQLITE_
366e0 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51  MUTEX_OS2,.** SQ
366f0 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
36700 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AD, and SQLITE_M
36710 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65  UTEX_W32 impleme
36720 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ntations.** are 
36730 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
36740 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69  use on OS/2, Uni
36750 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a  x, and Windows..
36760 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
36770 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
36780 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55  th the SQLITE_MU
36790 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72  TEX_APPDEF prepr
367a0 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f  ocessor.** macro
367b0 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22   defined (with "
367c0 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41  -DSQLITE_MUTEX_A
367d0 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20  PPDEF=1"), then 
367e0 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  no mutex.** impl
367f0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e  ementation is in
36800 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20  cluded with the 
36810 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73  library. In this
36820 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70   case the.** app
36830 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
36840 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75  pply a custom mu
36850 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
36860 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  on using the.** 
36870 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
36880 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20  UTEX] option of 
36890 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  the sqlite3_conf
368a0 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ig() function.**
368b0 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20   before calling 
368c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
368d0 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65  ze() or any othe
368e0 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33  r public sqlite3
368f0 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  _.** function th
36900 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  at calls sqlite3
36910 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 29 5e  _initialize().)^
36920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36930 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
36940 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61  ) routine alloca
36950 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74  tes a new.** mut
36960 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ex and returns a
36970 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20   pointer to it. 
36980 5e 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e  ^If it returns N
36990 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e  ULL.** that mean
369a0 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63  s that a mutex c
369b0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f  ould not be allo
369c0 63 61 74 65 64 2e 20 20 5e 53 51 4c 69 74 65 0a  cated.  ^SQLite.
369d0 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69  ** will unwind i
369e0 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74  ts stack and ret
369f0 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  urn an error.  ^
36a00 28 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  (The argument.**
36a10 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
36a20 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65  x_alloc() is one
36a30 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
36a40 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a  r constants:.**.
36a50 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
36a60 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
36a70 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ST.** <li>  SQLI
36a80 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
36a90 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
36aa0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
36ab0 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20  MASTER.** <li>  
36ac0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
36ad0 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20  TIC_MEM.** <li> 
36ae0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
36af0 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69  ATIC_MEM2.** <li
36b00 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
36b10 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c  STATIC_PRNG.** <
36b20 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
36b30 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20  X_STATIC_LRU.** 
36b40 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
36b50 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a  EX_STATIC_LRU2.*
36b60 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
36b70 5e 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63  ^The first two c
36b80 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c 49 54 45  onstants (SQLITE
36b90 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20  _MUTEX_FAST and 
36ba0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
36bb0 55 52 53 49 56 45 29 0a 2a 2a 20 63 61 75 73 65  URSIVE).** cause
36bc0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
36bd0 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65  lloc() to create
36be0 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e  .** a new mutex.
36bf0 20 20 5e 54 68 65 20 6e 65 77 20 6d 75 74 65 78    ^The new mutex
36c00 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68   is recursive wh
36c10 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
36c20 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20  RECURSIVE.** is 
36c30 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63  used but not nec
36c40 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e  essarily so when
36c50 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
36c60 53 54 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54  ST is used..** T
36c70 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  he mutex impleme
36c80 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
36c90 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20   need to make a 
36ca0 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
36cb0 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55  etween SQLITE_MU
36cc0 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e  TEX_RECURSIVE an
36cd0 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  d SQLITE_MUTEX_F
36ce0 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a  AST if it does.*
36cf0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20  * not want to.  
36d00 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c  ^SQLite will onl
36d10 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75  y request a recu
36d20 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a  rsive mutex in.*
36d30 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74  * cases where it
36d40 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e   really needs on
36d50 65 2e 20 20 5e 49 66 20 61 20 66 61 73 74 65 72  e.  ^If a faster
36d60 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d   non-recursive m
36d70 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
36d80 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  tation is availa
36d90 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20  ble on the host 
36da0 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75  platform, the mu
36db0 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a  tex subsystem.**
36dc0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75   might return su
36dd0 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65  ch a mutex in re
36de0 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45  sponse to SQLITE
36df0 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a  _MUTEX_FAST..**.
36e00 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72 20 61 6c  ** ^The other al
36e10 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73  lowed parameters
36e20 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
36e30 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e 79 74 68  x_alloc() (anyth
36e40 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20 74 68 61  ing other.** tha
36e50 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  n SQLITE_MUTEX_F
36e60 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AST and SQLITE_M
36e70 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20  UTEX_RECURSIVE) 
36e80 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61  each return.** a
36e90 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
36ea0 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e 67  atic preexisting
36eb0 20 6d 75 74 65 78 2e 20 20 5e 53 69 78 20 73 74   mutex.  ^Six st
36ec0 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
36ed0 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20  .** used by the 
36ee0 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20  current version 
36ef0 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75  of SQLite.  Futu
36f00 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
36f10 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64  QLite.** may add
36f20 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74   additional stat
36f30 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61  ic mutexes.  Sta
36f40 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 20  tic mutexes are 
36f50 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20  for internal.** 
36f60 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  use by SQLite on
36f70 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ly.  Application
36f80 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74  s that use SQLit
36f90 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64  e mutexes should
36fa0 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65  .** use only the
36fb0 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73   dynamic mutexes
36fc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
36fd0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f  ITE_MUTEX_FAST o
36fe0 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  r.** SQLITE_MUTE
36ff0 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a  X_RECURSIVE..**.
37000 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 69 66  ** ^Note that if
37010 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61   one of the dyna
37020 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65  mic mutex parame
37030 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54  ters (SQLITE_MUT
37040 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51  EX_FAST.** or SQ
37050 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
37060 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68  SIVE) is used th
37070 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  en sqlite3_mutex
37080 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75  _alloc().** retu
37090 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20  rns a different 
370a0 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63  mutex on every c
370b0 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f 72 20 74  all.  ^But for t
370c0 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74  he static.** mut
370d0 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61  ex types, the sa
370e0 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75  me mutex is retu
370f0 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61  rned on every ca
37100 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74  ll that has.** t
37110 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d  he same type num
37120 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
37130 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
37140 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61  ee() routine dea
37150 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69  llocates a previ
37160 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ously.** allocat
37170 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ed dynamic mutex
37180 2e 20 20 5e 53 51 4c 69 74 65 20 69 73 20 63 61  .  ^SQLite is ca
37190 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63  reful to dealloc
371a0 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e  ate every.** dyn
371b0 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20  amic mutex that 
371c0 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54  it allocates.  T
371d0 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
371e0 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69  es must not be i
371f0 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68  n.** use when th
37200 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  ey are deallocat
37210 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67 20  ed.  Attempting 
37220 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20  to deallocate a 
37230 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
37240 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
37250 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 20  ined behavior.  
37260 5e 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65  ^SQLite never de
37270 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73  allocates.** a s
37280 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a  tatic mutex..**.
37290 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
372a0 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e  mutex_enter() an
372b0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
372c0 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61  try() routines a
372d0 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74  ttempt.** to ent
372e0 65 72 20 61 20 6d 75 74 65 78 2e 20 20 5e 49 66  er a mutex.  ^If
372f0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
37300 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69  is already withi
37310 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20  n the mutex,.** 
37320 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
37330 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b  ter() will block
37340 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
37350 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65  ex_try() will re
37360 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42  turn.** SQLITE_B
37370 55 53 59 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  USY.  ^The sqlit
37380 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69  e3_mutex_try() i
37390 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
373a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20   [SQLITE_OK].** 
373b0 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20  upon successful 
373c0 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74 65 78 65  entry.  ^(Mutexe
373d0 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
373e0 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
373f0 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 65  RECURSIVE can be
37400 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c   entered multipl
37410 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73  e times by the s
37420 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  ame thread..** I
37430 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68 65  n such cases the
37440 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 20  ,.** mutex must 
37450 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71 75  be exited an equ
37460 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  al number of tim
37470 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 65  es before anothe
37480 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20  r thread.** can 
37490 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49 66 20 74  enter.)^  ^(If t
374a0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74  he same thread t
374b0 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e  ries to enter an
374c0 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20  y other.** kind 
374d0 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68  of mutex more th
374e0 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68  an once, the beh
374f0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
37500 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  ed..** SQLite wi
37510 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74  ll never exhibit
37520 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f  .** such behavio
37530 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65  r in its own use
37540 20 6f 66 20 6d 75 74 65 78 65 73 2e 29 5e 0a 2a   of mutexes.)^.*
37550 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73 79 73 74  *.** ^(Some syst
37560 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ems (for example
37570 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f  , Windows 95) do
37580 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65   not support the
37590 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d   operation.** im
375a0 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c  plemented by sql
375b0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
375c0 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74  .  On those syst
375d0 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  ems, sqlite3_mut
375e0 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c  ex_try().** will
375f0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53   always return S
37600 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54 68 65  QLITE_BUSY.  The
37610 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c   SQLite core onl
37620 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73  y ever uses.** s
37630 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
37640 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a  () as an optimiz
37650 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73  ation so this is
37660 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61   acceptable beha
37670 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  vior.)^.**.** ^T
37680 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
37690 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65  _leave() routine
376a0 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74   exits a mutex t
376b0 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  hat was.** previ
376c0 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ously entered by
376d0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
376e0 2e 20 20 20 5e 28 54 68 65 20 62 65 68 61 76 69  .   ^(The behavi
376f0 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
37700 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 20  ed if the mutex 
37710 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
37720 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 0a   entered by the.
37730 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  ** calling threa
37740 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 72  d or is not curr
37750 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e  ently allocated.
37760 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
37770 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72   never do either
37780 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
37790 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
377a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
377b0 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  r(), sqlite3_mut
377c0 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20  ex_try(), or.** 
377d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
377e0 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  ave() is a NULL 
377f0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c  pointer, then al
37800 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  l three routines
37810 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e 6f  .** behave as no
37820 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  -ops..**.** See 
37830 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d  also: [sqlite3_m
37840 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64  utex_held()] and
37850 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
37860 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73  notheld()]..*/.s
37870 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71  qlite3_mutex *sq
37880 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
37890 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  c(int);.void sql
378a0 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
378b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
378c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
378d0 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65  tex_enter(sqlite
378e0 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
378f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
37900 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
37910 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
37920 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74  utex_leave(sqlit
37930 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a  e3_mutex*);../*.
37940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
37950 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  ex Methods Objec
37960 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
37970 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
37980 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74 68  cture defines th
37990 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74  e low-level rout
379a0 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ines.** used to 
379b0 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 65  allocate and use
379c0 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20   mutexes..**.** 
379d0 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 66  Usually, the def
379e0 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c 65  ault mutex imple
379f0 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 69  mentations provi
37a00 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 72  ded by SQLite ar
37a10 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 2c  e.** sufficient,
37a20 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73 65   however the use
37a30 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f 6e  r has the option
37a40 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e 67   of substituting
37a50 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70   a custom.** imp
37a60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  lementation for 
37a70 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70 6c  specialized depl
37a80 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 65  oyments or syste
37a90 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51 4c  ms for which SQL
37aa0 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
37ab0 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61 62  provide a suitab
37ac0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
37ad0 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c  n. In this case,
37ae0 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 65   the user.** cre
37af0 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 74  ates and populat
37b00 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  es an instance o
37b10 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
37b20 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20 73   to pass.** to s
37b30 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
37b40 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20 5b  along with the [
37b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
37b60 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  TEX] option..** 
37b70 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e  Additionally, an
37b80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
37b90 73 20 73 74 72 75 63 74 75 72 65 20 63 61 6e 20  s structure can 
37ba0 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a 2a  be used as an.**
37bb0 20 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c 65   output variable
37bc0 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20 74   when querying t
37bd0 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74 68  he system for th
37be0 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78 0a  e current mutex.
37bf0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
37c00 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  n, using the [SQ
37c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
37c20 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  UTEX] option..**
37c30 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49  .** ^The xMutexI
37c40 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69 6e  nit method defin
37c50 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63  ed by this struc
37c60 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  ture is invoked 
37c70 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79  as.** part of sy
37c80 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74  stem initializat
37c90 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74  ion by the sqlit
37ca0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
37cb0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68  function..** ^Th
37cc0 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75  e xMutexInit rou
37cd0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 20 62 79  tine is calle by
37ce0 20 53 51 4c 69 74 65 20 65 78 61 63 74 6c 79 20   SQLite exactly 
37cf0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a  once for each.**
37d00 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
37d10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  to [sqlite3_init
37d20 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ialize()]..**.**
37d30 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20   ^The xMutexEnd 
37d40 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62  method defined b
37d50 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  y this structure
37d60 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a   is invoked as.*
37d70 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d  * part of system
37d80 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65   shutdown by the
37d90 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
37da0 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  n() function. Th
37db0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
37dc0 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68  ion of this meth
37dd0 6f 64 20 69 73 20 65 78 70 65 63 74 65 64 20 74  od is expected t
37de0 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75  o release all ou
37df0 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73  tstanding.** res
37e00 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20  ources obtained 
37e10 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74  by the mutex met
37e20 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  hods implementat
37e30 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a  ion, especially.
37e40 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65  ** those obtaine
37e50 64 20 62 79 20 74 68 65 20 78 4d 75 74 65 78 49  d by the xMutexI
37e60 6e 69 74 20 6d 65 74 68 6f 64 2e 20 20 5e 54 68  nit method.  ^Th
37e70 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a  e xMutexEnd().**
37e80 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
37e90 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  voked exactly on
37ea0 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c  ce for each call
37eb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   to [sqlite3_shu
37ec0 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  tdown()]..**.** 
37ed0 5e 28 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  ^(The remaining 
37ee0 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65  seven methods de
37ef0 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
37f00 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 41  ructure (xMutexA
37f10 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46  lloc,.** xMutexF
37f20 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72  ree, xMutexEnter
37f30 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75  , xMutexTry, xMu
37f40 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78  texLeave, xMutex
37f50 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74  Held and.** xMut
37f60 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65  exNotheld) imple
37f70 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69  ment the followi
37f80 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 72  ng interfaces (r
37f90 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a  espectively):.**
37fa0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
37fb0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
37fc0 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69  ex_alloc()] </li
37fd0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
37fe0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
37ff0 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
38000 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
38010 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c  tex_enter()] </l
38020 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
38030 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
38040 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
38050 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
38060 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c  tex_leave()] </l
38070 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
38080 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
38090 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  d()] </li>.**   
380a0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
380b0 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20  utex_notheld()] 
380c0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  </li>.** </ul>)^
380d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20  .**.** The only 
380e0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 74 68  difference is th
380f0 61 74 20 74 68 65 20 70 75 62 6c 69 63 20 73 71  at the public sq
38100 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69  lite3_XXX functi
38110 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a  ons enumerated.*
38120 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79  * above silently
38130 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f   ignore any invo
38140 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73  cations that pas
38150 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
38160 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
38170 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e   valid mutex han
38180 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65  dle. The impleme
38190 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
381a0 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a  methods defined.
381b0 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72 75 63  ** by this struc
381c0 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71  ture are not req
381d0 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  uired to handle 
381e0 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 72  this case, the r
381f0 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73  esults.** of pas
38200 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
38210 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
38220 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e   valid mutex han
38230 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65  dle are undefine
38240 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73  d.** (i.e. it is
38250 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70   acceptable to p
38260 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d  rovide an implem
38270 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65  entation that se
38280 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74  gfaults if.** it
38290 20 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c   is passed a NUL
382a0 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2a 0a 2a  L pointer)..**.*
382b0 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74  * The xMutexInit
382c0 28 29 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 62  () method must b
382d0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 5e  e threadsafe.  ^
382e0 49 74 20 6d 75 73 74 20 62 65 20 68 61 72 6d 6c  It must be harml
382f0 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  ess to.** invoke
38300 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75   xMutexInit() mu
38310 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
38320 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
38330 65 73 73 20 61 6e 64 20 77 69 74 68 6f 75 74 0a  ess and without.
38340 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 63  ** intervening c
38350 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65 78 45 6e  alls to xMutexEn
38360 64 28 29 2e 20 20 53 65 63 6f 6e 64 20 61 6e 64  d().  Second and
38370 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
38380 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65 78 49 6e  s to.** xMutexIn
38390 69 74 28 29 20 6d 75 73 74 20 62 65 20 6e 6f 2d  it() must be no-
383a0 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 78 4d 75 74  ops..**.** ^xMut
383b0 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 6e 6f  exInit() must no
383c0 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d  t use SQLite mem
383d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  ory allocation (
383e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
383f0 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73 20 61 73  )].** and its as
38400 73 6f 63 69 61 74 65 73 29 2e 20 20 5e 53 69 6d  sociates).  ^Sim
38410 69 6c 61 72 6c 79 2c 20 78 4d 75 74 65 78 41 6c  ilarly, xMutexAl
38420 6c 6f 63 28 29 20 6d 75 73 74 20 6e 6f 74 20 75  loc() must not u
38430 73 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79  se SQLite memory
38440 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  .** allocation f
38450 6f 72 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  or a static mute
38460 78 2e 20 20 5e 48 6f 77 65 76 65 72 20 78 4d 75  x.  ^However xMu
38470 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61 79 20 75  texAlloc() may u
38480 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 65 6d  se SQLite.** mem
38490 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
384a0 6f 72 20 61 20 66 61 73 74 20 6f 72 20 72 65 63  or a fast or rec
384b0 75 72 73 69 76 65 20 6d 75 74 65 78 2e 0a 2a 2a  ursive mutex..**
384c0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
384d0 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 4d 75 74   invoke the xMut
384e0 65 78 45 6e 64 28 29 20 6d 65 74 68 6f 64 20 77  exEnd() method w
384f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  hen [sqlite3_shu
38500 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a 2a 20 63  tdown()] is.** c
38510 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e 6c 79 20  alled, but only 
38520 69 66 20 74 68 65 20 70 72 69 6f 72 20 63 61 6c  if the prior cal
38530 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e 69 74 20  l to xMutexInit 
38540 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54 45 5f  returned SQLITE_
38550 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75 74 65 78  OK..** If xMutex
38560 49 6e 69 74 20 66 61 69 6c 73 20 69 6e 20 61 6e  Init fails in an
38570 79 20 77 61 79 2c 20 69 74 20 69 73 20 65 78 70  y way, it is exp
38580 65 63 74 65 64 20 74 6f 20 63 6c 65 61 6e 20 75  ected to clean u
38590 70 20 61 66 74 65 72 20 69 74 73 65 6c 66 0a 2a  p after itself.*
385a0 2a 20 70 72 69 6f 72 20 74 6f 20 72 65 74 75 72  * prior to retur
385b0 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ning..*/.typedef
385c0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
385d0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73 71  mutex_methods sq
385e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
385f0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
38600 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
38610 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  s {.  int (*xMut
38620 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a 20  exInit)(void);. 
38630 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e 64   int (*xMutexEnd
38640 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69 74  )(void);.  sqlit
38650 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74  e3_mutex *(*xMut
38660 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a 20  exAlloc)(int);. 
38670 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46 72   void (*xMutexFr
38680 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ee)(sqlite3_mute
38690 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  x *);.  void (*x
386a0 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c 69  MutexEnter)(sqli
386b0 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
386c0 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79 29  int (*xMutexTry)
386d0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
386e0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74  );.  void (*xMut
386f0 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65 33  exLeave)(sqlite3
38700 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74  _mutex *);.  int
38710 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28 73   (*xMutexHeld)(s
38720 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
38730 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 4e  .  int (*xMutexN
38740 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33 5f  otheld)(sqlite3_
38750 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a  mutex *);.};../*
38760 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
38770 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f 6e  tex Verification
38780 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
38790 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
387a0 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c  x_held() and sql
387b0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
387c0 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  ld() routines.**
387d0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
387e0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73  r use inside ass
387f0 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
38800 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63  .  ^The SQLite c
38810 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65  ore.** never use
38820 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  s these routines
38830 20 65 78 63 65 70 74 20 69 6e 73 69 64 65 20 61   except inside a
38840 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64 20 61  n assert() and a
38850 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
38860 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f  re advised to fo
38870 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66  llow the lead of
38880 20 74 68 65 20 63 6f 72 65 2e 20 20 5e 54 68 65   the core.  ^The
38890 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c   SQLite core onl
388a0 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d  y.** provides im
388b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
388c0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
388d0 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
388e0 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  iled.** with the
388f0 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c   SQLITE_DEBUG fl
38900 61 67 2e 20 20 5e 45 78 74 65 72 6e 61 6c 20 6d  ag.  ^External m
38910 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74