/ Hex Artifact Content
Login

Artifact bfab0d236f8aabe8b5a876b971cb6a9a9611741c:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
41d0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
41e0: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
41f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4200: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4210: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4220: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4230: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4250: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4260: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4270: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4280: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4290: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42a0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42b0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
42c0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
42d0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
42e0: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
42f0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4310: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4320: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4330: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4360: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4370: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4380: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4390: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43a0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43b0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
43c0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
43f0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4400: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4410: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4420: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4430: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4440: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4450: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4460: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4470: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4480: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4490: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44a0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44b0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
44c0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
44f0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4500: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4510: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4520: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4530: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4540: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4550: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4560: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4570: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4580: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4590: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45a0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45b0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
45c0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
45d0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
45e0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
45f0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4610: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4620: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4630: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4640: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4650: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4660: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4670: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4680: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4690: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46a0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46b0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
46c0: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
46d0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
46e0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
46f0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4700: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4710: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4720: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4730: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4740: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4750: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4760: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4770: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4780: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4790: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47a0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47b0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
47c0: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
47d0: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
47e0: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
47f0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4800: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4810: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4820: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4830: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4840: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4850: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4860: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4870: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4880: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4890: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48a0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48b0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
48c0: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
48d0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
48e0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
48f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4900: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4910: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4920: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4930: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4940: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4950: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4960: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
4970: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
4980: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
4990: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49a0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49b0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
49c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
49d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
49e0: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
49f0: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a00: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a10: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a20: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a30: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a40: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a50: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4a60: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4a70: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4a80: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4a90: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4aa0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4ab0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4ac0: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4ad0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ae0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4af0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b00: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b20: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b40: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4b60: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4b70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4b80: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ba0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4bc0: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4bd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4be0: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4bf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c00: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c20: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c40: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4c60: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4c70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4c80: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4c90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ca0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cb0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4cc0: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4cd0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4ce0: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4cf0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d00: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d20: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d40: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4d60: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4da0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4de0: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e20: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4e60: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ea0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f20: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
4fe0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
4ff0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
5000: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5010: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5020: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5030: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5040: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5050: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5060: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5070: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5080: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  EN | (1<<8))../*
5090: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
50a0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
50b0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
50c0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
50d0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
50e0: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
50f0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5100: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5110: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5120: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5130: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5140: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  r to the xOpen m
5150: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
5160: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
5170: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5180: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5190: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
51a0: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
51b0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
51c0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
51d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
51e0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
51f0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
5200: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5210: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5220: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
5230: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
5240: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
5250: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5260: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5270: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5280: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5290: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
52a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
52b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
52c0: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
52d0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
52e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
52f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
5300: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
5310: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
5320: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5330: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5340: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5350: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
5360: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5370: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5380: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
5390: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
53a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
53b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
53c0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
53d0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
53e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
53f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5400: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
5410: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
5420: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5430: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5440: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
5450: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
5460: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5470: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
5480: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
5490: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
54a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
54b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
54c0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
54d0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
54e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
54f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
5500: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
5510: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
5520: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5530: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5540: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
5550: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
5560: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
5570: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5580: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5590: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
55a0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
55b0: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
55c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
55d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
55e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
55f0: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
5600: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
5610: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5620: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5630: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
5640: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5650: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
5660: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
5670: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
5680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5690: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
56a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
56b0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
56c0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
56d0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
56e0: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
56f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5700: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
5710: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
5720: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
5730: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
5740: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
5750: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
5760: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
5770: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
5780: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
5790: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
57a0: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
57b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
57c0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
57d0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
57e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
57f0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
5800: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
5810: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
5820: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
5830: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5840: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
5850: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
5860: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
5870: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
5880: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
5890: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
58a0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
58b0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
58c0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
58d0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
58e0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
58f0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
5900: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
5910: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
5920: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
5930: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
5940: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
5950: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
5960: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
5970: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
5980: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
5990: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
59a0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
59b0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
59c0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
59d0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
59e0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
59f0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
5a00: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
5a10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5a20: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
5a30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5a40: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5a50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5a60: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
5a70: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
5a80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a90: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
5aa0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ab0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
5ac0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ad0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
5ae0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
5af0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5b00: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
5b10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5b20: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
5b30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5b50: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
5b60: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b70: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
5b80: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ba0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
5bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5bc0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5bd0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5be0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
5bf0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
5c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5c10: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5c20: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5c30: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5c40: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
5c50: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
5c60: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
5c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c80: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
5c90: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
5ca0: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
5cb0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
5cc0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
5cd0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
5ce0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
5cf0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5d00: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
5d10: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
5d20: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
5d30: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
5d40: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
5d50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5d60: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
5d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d80: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
5d90: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
5da0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
5db0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
5dc0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
5dd0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
5de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5df0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
5e00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e10: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
5e20: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
5e30: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
5e40: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
5e50: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
5e60: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
5e70: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
5e80: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5e90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5ea0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
5eb0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
5ec0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5ed0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5ee0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5ef0: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5f00: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5f10: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5f20: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5f30: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5f40: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5f50: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5f60: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
5f70: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
5f80: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
5f90: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
5fa0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
5fb0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
5fc0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
5fd0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
5fe0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
5ff0: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
6000: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
6010: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
6020: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
6030: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
6040: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
6050: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
6060: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
6070: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
6080: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
6090: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
60a0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
60b0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
60c0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
60d0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
60e0: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
60f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
6100: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
6110: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
6120: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
6130: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
6140: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
6150: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
6160: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
6170: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
6180: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
6190: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
61a0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
61b0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
61c0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
61d0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
61e0: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
61f0: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
6200: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
6210: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
6220: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
6230: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
6240: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
6250: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
6260: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
6270: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
6280: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
6290: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
62a0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
62b0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
62c0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
62d0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
62e0: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
62f0: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
6300: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
6310: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
6320: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
6330: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
6340: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6350: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
6360: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6370: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
6380: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
6390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
63a0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
63b0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
63c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
63d0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
63e0: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
63f0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
6400: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
6410: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
6420: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
6430: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
6440: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
6450: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
6460: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
6470: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
6480: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
6490: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
64a0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
64b0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
64c0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
64d0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
64e0: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
64f0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
6500: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6510: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
6520: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
6530: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
6540: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
6550: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
6560: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
6570: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
6580: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
6590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
65a0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
65b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
65c0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
65d0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
65e0: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
65f0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6600: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6610: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
6620: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
6630: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
6640: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
6650: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
6660: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  en method popula
6670: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
6680: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
6690: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
66a0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
66b0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
66c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
66d0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
66e0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
66f0: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
6700: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
6710: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
6720: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
6730: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
6740: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
6750: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
6760: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
6770: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6780: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
6790: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
67a0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
67b0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
67c0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
67d0: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
67e0: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
67f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
6800: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
6810: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
6820: 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e  ven if the xOpen
6830: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6840: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6850: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6860: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6870: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6880: 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a   a failed xOpen.
6890: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f  ** is for the xO
68a0: 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73  pen to set the s
68b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
68c0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20  hods element to 
68d0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
68e0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
68f0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
6900: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
6910: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
6920: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
6930: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
6940: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
6950: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
6960: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
6970: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
6980: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
6990: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
69a0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
69b0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
69c0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
69d0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
69e0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
69f0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
6a00: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
6a10: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
6a20: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6a30: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
6a40: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
6a50: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
6a60: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6a70: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
6a80: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
6a90: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
6aa0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6ab0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
6ac0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6ad0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
6ae0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
6af0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
6b00: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
6b10: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
6b20: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
6b30: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
6b40: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
6b50: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
6b60: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
6b70: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
6b80: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
6b90: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
6ba0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
6bb0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
6bc0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
6bd0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
6be0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
6bf0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
6c00: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
6c10: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
6c20: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
6c30: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
6c40: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
6c50: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6c60: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6c70: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6c80: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
6c90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6ca0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
6cb0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
6cc0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
6cd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6ce0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
6cf0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
6d00: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
6d10: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
6d20: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
6d30: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
6d40: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
6d50: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
6d60: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
6d70: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
6d80: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
6d90: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
6da0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
6db0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
6dc0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
6dd0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
6de0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
6df0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
6e00: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
6e10: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
6e20: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
6e30: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
6e40: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
6e50: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
6e60: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
6e70: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
6e80: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
6e90: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
6ea0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
6eb0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
6ec0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
6ed0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
6ee0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
6ef0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
6f00: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
6f10: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
6f20: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
6f30: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6f40: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6f50: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6f60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6f70: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
6f80: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
6f90: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
6fa0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
6fb0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
6fc0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
6fd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
6fe0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
6ff0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7000: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7010: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7020: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7030: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7040: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7050: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
7060: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
7070: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7080: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7090: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
70a0: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
70b0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
70c0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
70d0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
70e0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
70f0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7100: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7110: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7120: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7130: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7140: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7150: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7160: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7170: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7180: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7190: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
71a0: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
71b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
71c0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
71d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
71e0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
71f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7200: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7210: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7220: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7230: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7240: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7250: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7260: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7270: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7280: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7290: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
72a0: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
72b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
72c0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
72d0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
72e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
72f0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7300: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7310: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
7320: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7330: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7340: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
7350: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
7360: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
7370: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7380: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7390: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
73a0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
73b0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
73c0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
73d0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
73e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
73f0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7400: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7410: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
7420: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7430: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
7440: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
7450: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
7460: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
7470: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7480: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7490: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
74a0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
74b0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
74c0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
74d0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
74e0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
74f0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7500: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7510: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
7520: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
7530: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
7540: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
7550: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
7560: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
7570: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
7580: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
7590: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
75a0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
75b0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
75c0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
75d0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
75e0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
75f0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7600: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7610: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
7620: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
7630: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7640: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7650: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7660: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
7670: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
7680: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
7690: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
76a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
76b0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
76c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
76d0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
76e0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
76f0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
7700: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
7710: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
7720: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
7730: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
7740: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
7750: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7760: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
7770: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
7780: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
7790: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
77a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
77b0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
77c0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
77d0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
77e0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
77f0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
7800: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
7810: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7820: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
7830: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
7840: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7850: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
7860: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
7870: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
7880: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
7890: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
78a0: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
78b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
78c0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
78d0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
78e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
78f0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7900: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7910: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
7920: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
7930: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7940: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
7950: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
7960: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
7970: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
7980: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
7990: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
79a0: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
79b0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
79c0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
79d0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
79e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
79f0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
7a00: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7a10: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7a20: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
7a30: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
7a40: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
7a50: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
7a60: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
7a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
7a80: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
7a90: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
7aa0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
7ab0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
7ac0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
7ad0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
7ae0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7af0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7b00: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
7b10: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
7b20: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
7b30: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
7b40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7b50: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
7b60: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
7b70: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
7b80: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
7b90: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7ba0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
7bb0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
7bc0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
7bd0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
7be0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7bf0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7c00: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
7c10: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
7c20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7c30: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
7c40: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7c50: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
7c60: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
7c70: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
7c80: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
7c90: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
7ca0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
7cb0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
7cc0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
7cd0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
7ce0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
7cf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7d00: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
7d10: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
7d20: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
7d30: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
7d40: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
7d50: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
7d60: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
7d70: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
7d80: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
7d90: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
7da0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
7db0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
7dc0: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
7dd0: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
7de0: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
7df0: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
7e00: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
7e10: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
7e20: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
7e30: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
7e40: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
7e50: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
7e60: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
7e70: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
7e80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
7e90: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
7ea0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
7eb0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
7ec0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
7ed0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
7ee0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
7ef0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
7f00: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
7f10: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
7f20: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
7f30: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
7f40: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
7f50: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
7f60: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
7f70: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
7f80: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
7f90: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
7fa0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
7fb0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
7fc0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
7fd0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
7fe0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
7ff0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8000: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8010: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8020: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8030: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8040: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
8050: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ems..**.** The [
8060: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
8070: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
8080: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
8090: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
80a0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
80b0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
80c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
80d0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
80e0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
80f0: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
8100: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8110: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
8120: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
8130: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
8140: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ..**.** ^(The [S
8150: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8160: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
8170: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
8180: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
8190: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
81a0: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
81b0: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
81c0: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
81d0: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
81e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
81f0: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8200: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8210: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
8220: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8230: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
8240: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
8250: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
8260: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
8270: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
8280: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
8290: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
82a0: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
82b0: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
82c0: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
82d0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
82e0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
82f0: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8300: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8310: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
8320: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
8330: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
8340: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
8350: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
8360: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
8370: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
8380: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
8390: 72 65 20 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66  re it.  .*/.#def
83a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
83b0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
83c0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
83d0: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
83e0: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
83f0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
8400: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
8410: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
8420: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
8430: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
8440: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8450: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
8460: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
8470: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8480: 49 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66  IZE       6.#def
8490: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
84a0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
84b0: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
84c0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
84d0: 49 54 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a  ITTED     8.../*
84e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
84f0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
8500: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
8510: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
8520: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
8530: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
8540: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
8550: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
8560: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
8570: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
8580: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
8590: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
85a0: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
85b0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
85c0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
85d0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
85e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
85f0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
8600: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
8610: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
8620: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
8630: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
8640: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
8650: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
8660: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
8670: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
8680: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
8690: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
86a0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
86b0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
86c0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
86d0: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
86e0: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
86f0: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
8700: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
8710: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
8720: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
8730: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
8740: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
8750: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  m"..**.** The va
8760: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
8770: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
8780: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
8790: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
87a0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
87b0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
87c0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
87d0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
87e0: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
87f0: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
8800: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
8810: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
8820: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
8830: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
8840: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
8850: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
8860: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
8870: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
8880: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
8890: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
88a0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
88b0: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
88c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
88d0: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
88e0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
88f0: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
8900: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
8910: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
8920: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
8930: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
8940: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
8950: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
8960: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
8970: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
8980: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
8990: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
89a0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
89b0: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
89c0: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
89d0: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
89e0: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
89f0: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
8a00: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
8a10: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
8a20: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
8a30: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
8a40: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
8a50: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
8a60: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
8a70: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
8a80: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
8a90: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
8aa0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
8ab0: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
8ac0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
8ad0: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
8ae0: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
8af0: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
8b00: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
8b10: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
8b20: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
8b30: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
8b40: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
8b50: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
8b60: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
8b70: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
8b80: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
8b90: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
8ba0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
8bb0: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
8bc0: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
8bd0: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
8be0: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
8bf0: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
8c00: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
8c10: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
8c20: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
8c30: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
8c40: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
8c50: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
8c60: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
8c70: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  .**.** ^SQLite g
8c80: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
8c90: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
8ca0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
8cb0: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
8cc0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
8cd0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
8ce0: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
8cf0: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
8d00: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
8d10: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
8d20: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
8d30: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
8d40: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
8d50: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
8d60: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
8d70: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
8d80: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
8d90: 0a 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65  .** 10 alphanume
8da0: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
8db0: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
8dc0: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
8dd0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
8de0: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
8df0: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
8e00: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
8e10: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
8e20: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
8e30: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
8e40: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
8e50: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
8e60: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
8e70: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
8e80: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
8e90: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
8ea0: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
8eb0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
8ec0: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
8ed0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
8ee0: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
8ef0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
8f00: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
8f10: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
8f20: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
8f30: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
8f40: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
8f50: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
8f60: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
8f70: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
8f80: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
8f90: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
8fa0: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
8fb0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
8fc0: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
8fd0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
8fe0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
8ff0: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
9000: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
9010: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
9020: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
9030: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
9040: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
9050: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
9060: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
9070: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
9080: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
9090: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
90a0: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
90b0: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
90c0: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
90d0: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
90e0: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
90f0: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
9100: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
9110: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
9120: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
9130: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
9140: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
9150: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
9160: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
9170: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
9180: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
9190: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
91a0: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
91b0: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
91c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
91d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
91e0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
91f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
9200: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
9210: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
9220: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
9230: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
9240: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
9250: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
9260: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
9270: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9280: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
9290: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
92a0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
92b0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
92c0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
92d0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
92e0: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
92f0: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
9300: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
9310: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
9320: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
9330: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
9340: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
9350: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
9360: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
9370: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
9380: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
9390: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
93a0: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
93b0: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
93c0: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
93d0: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
93e0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
93f0: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
9400: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
9410: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
9420: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
9430: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
9440: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
9450: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
9460: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
9470: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
9480: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
9490: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
94a0: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
94b0: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
94c0: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
94d0: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
94e0: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
94f0: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
9500: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
9510: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
9520: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
9530: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
9540: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
9550: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
9560: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
9570: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
9580: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
9590: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
95a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
95b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
95c0: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
95d0: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
95e0: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
95f0: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
9600: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
9610: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
9620: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
9630: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
9640: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
9650: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
9660: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
9670: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
9680: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
9690: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
96a0: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
96b0: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
96c0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
96d0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
96e0: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
96f0: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
9700: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
9710: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
9720: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
9730: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
9740: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
9750: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
9760: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
9770: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
9780: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
9790: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
97a0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
97b0: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
97c0: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
97d0: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
97e0: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
97f0: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
9800: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
9810: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
9820: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
9830: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
9840: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
9850: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
9860: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
9870: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
9880: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
9890: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
98a0: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
98b0: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
98c0: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
98d0: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
98e0: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
98f0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
9900: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
9910: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
9920: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
9930: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
9940: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
9950: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
9960: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
9970: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
9980: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
9990: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
99a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
99b0: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
99c0: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
99d0: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
99e0: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
99f0: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
9a00: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
9a10: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
9a20: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
9a30: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
9a40: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
9a50: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
9a60: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
9a70: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
9a80: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
9a90: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
9aa0: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
9ab0: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
9ac0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
9ad0: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
9ae0: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
9af0: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
9b00: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
9b10: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
9b20: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
9b30: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
9b40: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
9b50: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
9b60: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
9b70: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
9b80: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
9b90: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
9ba0: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
9bb0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
9bc0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
9bd0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
9be0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
9bf0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
9c00: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
9c10: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
9c20: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
9c30: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
9c40: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
9c50: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
9c60: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
9c70: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
9c80: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
9c90: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
9ca0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
9cb0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
9cc0: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
9cd0: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
9ce0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
9cf0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
9d00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
9d10: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
9d20: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
9d30: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
9d40: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
9d50: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
9d60: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
9d70: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
9d80: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
9d90: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
9da0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
9db0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
9dc0: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
9dd0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
9de0: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
9df0: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
9e00: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
9e10: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
9e20: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
9e30: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
9e40: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
9e50: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
9e60: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
9e70: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
9e80: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
9e90: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
9ea0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
9eb0: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
9ec0: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
9ed0: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
9ee0: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
9ef0: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
9f00: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
9f10: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
9f20: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
9f30: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
9f40: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
9f50: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
9f60: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
9f70: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
9f80: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
9f90: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
9fa0: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
9fb0: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
9fc0: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
9fd0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
9fe0: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
9ff0: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
a000: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
a010: 72 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38  r multipled by 8
a020: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
a030: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
a040: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
a050: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
a060: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
a070: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
a080: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
a090: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
a0a0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
a0b0: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
a0c0: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
a0d0: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
a0e0: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
a0f0: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
a100: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
a110: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
a120: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
a130: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
a140: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
a150: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
a160: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
a170: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
a180: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
a190: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
a1a0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
a1b0: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
a1c0: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
a1d0: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
a1e0: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
a1f0: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
a200: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
a210: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
a220: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
a230: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
a240: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
a250: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
a260: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
a270: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
a280: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
a290: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
a2a0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
a2b0: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
a2c0: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
a2d0: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
a2e0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
a2f0: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
a300: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
a310: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
a320: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
a330: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
a340: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
a350: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
a360: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
a370: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
a380: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
a390: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
a3a0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
a3b0: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
a3c0: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
a3d0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
a3e0: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
a3f0: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
a400: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
a410: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
a420: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
a430: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
a440: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
a450: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
a460: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
a470: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
a480: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
a490: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
a4a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
a4b0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
a4c0: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
a4d0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
a4e0: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
a4f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
a500: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
a510: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
a520: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
a530: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
a540: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
a550: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
a560: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
a570: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
a580: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
a590: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
a5a0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
a5b0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
a5c0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
a5d0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
a5e0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
a5f0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
a600: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
a610: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
a620: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
a630: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
a640: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
a650: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
a660: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
a670: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
a680: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
a690: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a6a0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a6b0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
a6c0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
a6d0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
a6e0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
a6f0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
a700: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a710: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a720: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
a730: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
a740: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a750: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a760: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
a770: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
a780: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
a790: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
a7a0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
a7b0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
a7c0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
a7d0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
a7e0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
a7f0: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
a800: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
a810: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
a820: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
a830: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
a840: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
a850: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
a860: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
a870: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
a880: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
a890: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
a8a0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
a8b0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
a8c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
a8d0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
a8e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
a8f0: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
a900: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
a910: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
a920: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
a930: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
a940: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
a950: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
a960: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
a970: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
a980: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a990: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a9a0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
a9b0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
a9c0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
a9d0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
a9e0: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
a9f0: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
aa00: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
aa10: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
aa20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
aa30: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
aa40: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
aa50: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
aa60: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
aa70: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
aa80: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
aa90: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
aaa0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
aab0: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
aac0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
aad0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
aae0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
aaf0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
ab00: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
ab10: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
ab20: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
ab30: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ab40: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ab50: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
ab60: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
ab70: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ab80: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ab90: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
aba0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
abb0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
abc0: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
abd0: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
abe0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
abf0: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
ac00: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
ac10: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
ac20: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
ac30: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
ac40: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
ac50: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
ac60: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
ac70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
ac80: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
ac90: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
aca0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
acb0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
acc0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
acd0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
ace0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
acf0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
ad00: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
ad10: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
ad20: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
ad30: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
ad40: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ad50: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
ad60: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
ad70: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
ad80: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
ad90: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
ada0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
adb0: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
adc0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
add0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
ade0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
adf0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
ae00: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
ae10: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
ae20: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
ae30: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
ae40: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
ae50: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
ae60: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
ae70: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
ae80: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
ae90: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
aea0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
aeb0: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
aec0: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
aed0: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
aee0: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
aef0: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
af00: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
af10: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
af20: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
af30: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
af40: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
af50: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
af60: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
af70: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
af80: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
af90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
afa0: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
afb0: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
afc0: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
afd0: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
afe0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
aff0: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
b000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
b010: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
b020: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b030: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
b040: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
b050: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
b060: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
b070: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
b080: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
b090: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
b0a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b0b0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
b0c0: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
b0d0: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
b0e0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
b0f0: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
b100: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
b110: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
b120: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
b130: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
b140: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
b150: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
b160: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
b170: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
b180: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
b190: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
b1a0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
b1b0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
b1c0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
b1d0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
b1e0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
b1f0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
b200: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
b210: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
b220: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
b230: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
b240: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
b250: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
b260: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
b270: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
b280: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
b290: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
b2a0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
b2b0: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
b2c0: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
b2d0: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
b2e0: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
b2f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
b300: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
b310: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
b320: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
b330: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
b340: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
b350: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
b360: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
b370: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
b380: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
b390: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
b3a0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
b3b0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
b3c0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
b3d0: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
b3e0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
b3f0: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
b400: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
b410: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
b420: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
b430: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
b440: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
b450: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
b460: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
b470: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
b480: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
b490: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
b4a0: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
b4b0: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
b4c0: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
b4d0: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
b4e0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
b4f0: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
b500: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
b510: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
b520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
b530: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
b540: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
b550: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
b560: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
b570: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
b580: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b590: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
b5a0: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
b5b0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
b5c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
b5d0: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
b5e0: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
b5f0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
b600: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
b610: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
b620: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
b630: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
b640: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
b650: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
b660: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
b670: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
b680: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
b690: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
b6a0: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
b6b0: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
b6c0: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
b6d0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
b6e0: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
b6f0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
b700: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
b710: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
b720: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
b730: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
b740: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
b750: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
b760: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
b770: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
b780: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
b790: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
b7a0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
b7b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
b7c0: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
b7d0: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
b7e0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
b7f0: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
b800: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
b810: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
b820: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
b830: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
b840: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
b850: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
b860: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
b870: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
b880: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b890: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
b8a0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
b8b0: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
b8c0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
b8d0: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
b8e0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
b8f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
b900: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
b910: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
b920: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b930: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
b940: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
b950: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
b960: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
b970: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
b980: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
b990: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
b9a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b9b0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
b9c0: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
b9d0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b9e0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
b9f0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
ba00: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
ba10: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
ba20: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
ba30: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
ba40: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
ba50: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
ba60: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
ba70: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
ba80: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
ba90: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
baa0: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
bab0: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
bac0: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
bad0: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
bae0: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
baf0: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
bb00: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
bb10: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
bb20: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
bb30: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
bb40: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
bb50: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
bb60: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
bb70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
bb80: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
bb90: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
bba0: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
bbb0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
bbc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bbd0: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
bbe0: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
bbf0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
bc00: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
bc10: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
bc20: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
bc30: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
bc40: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
bc50: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
bc60: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
bc70: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
bc80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
bc90: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
bca0: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
bcb0: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
bcc0: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
bcd0: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
bce0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
bcf0: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
bd00: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
bd10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bd20: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
bd30: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
bd40: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
bd50: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
bd60: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
bd70: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
bd80: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
bd90: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
bda0: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
bdb0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
bdc0: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
bdd0: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
bde0: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
bdf0: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
be00: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
be10: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
be20: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
be30: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
be40: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
be50: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
be60: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
be70: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
be80: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
be90: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
bea0: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
beb0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
bec0: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
bed0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
bee0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
bef0: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
bf00: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
bf10: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
bf20: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
bf30: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
bf40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
bf50: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
bf60: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
bf70: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
bf80: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
bf90: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
bfa0: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
bfb0: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
bfc0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
bfd0: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
bfe0: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
bff0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
c000: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
c010: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
c020: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
c030: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
c040: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
c050: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
c060: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
c070: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
c080: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
c090: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
c0a0: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
c0b0: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
c0c0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
c0d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
c0e0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
c0f0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
c100: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
c110: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
c120: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
c130: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
c140: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
c150: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
c160: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
c170: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
c180: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
c190: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
c1a0: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
c1b0: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
c1c0: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
c1d0: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
c1e0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
c1f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
c200: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
c210: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
c220: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
c230: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
c240: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
c250: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
c260: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
c270: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
c280: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c290: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
c2a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c2b0: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
c2c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
c2d0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
c2e0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
c2f0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
c300: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
c310: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c320: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
c330: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
c340: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
c350: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
c360: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
c370: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
c380: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
c390: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
c3a0: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
c3b0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
c3c0: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
c3d0: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
c3e0: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
c3f0: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
c400: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
c410: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
c420: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
c430: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
c440: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
c450: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
c460: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
c470: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
c480: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
c490: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
c4a0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
c4b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
c4c0: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
c4d0: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
c4e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
c4f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
c500: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
c510: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
c520: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
c530: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
c540: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
c550: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
c560: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
c570: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c580: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
c590: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
c5a0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
c5b0: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
c5c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
c5d0: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
c5e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
c5f0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
c600: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
c610: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
c620: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
c630: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
c640: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
c650: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
c660: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
c670: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
c680: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
c690: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
c6a0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
c6b0: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
c6c0: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
c6d0: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
c6e0: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
c6f0: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
c700: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
c710: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
c720: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
c730: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
c740: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
c750: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
c760: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
c770: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
c780: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
c790: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
c7a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
c7b0: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
c7c0: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
c7d0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
c7e0: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
c7f0: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
c800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
c810: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
c820: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
c830: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
c840: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
c850: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
c860: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
c870: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
c880: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c890: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
c8a0: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
c8b0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
c8c0: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
c8d0: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
c8e0: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
c8f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
c900: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
c910: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c920: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
c930: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
c940: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
c950: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
c960: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
c970: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
c980: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
c990: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
c9a0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
c9b0: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
c9c0: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
c9d0: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
c9e0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c9f0: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
ca00: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
ca10: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
ca20: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
ca30: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
ca40: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
ca50: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
ca60: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
ca70: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
ca80: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
ca90: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
caa0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51  nding on the [SQ
cab0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
cac0: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
cad0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
cae0: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
caf0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
cb00: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
cb10: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
cb20: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
cb30: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
cb40: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
cb50: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
cb60: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
cb70: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
cb80: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
cb90: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
cba0: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
cbb0: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
cbc0: 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
cbd0: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
cbe0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
cbf0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
cc00: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
cc10: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tions.**.** The 
cc20: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
cc30: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
cc40: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
cc50: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
cc60: 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
cc70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
cc80: 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
cc90: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
cca0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
ccb0: 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
ccc0: 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
ccd0: 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
cce0: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
ccf0: 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
cd00: 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
cd10: 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a   argument)..**.*
cd20: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
cd30: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
cd40: 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
cd50: 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b  ..)  is the.** [
cd60: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
cd70: 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66  LOOKASIDE | conf
cd80: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20  iguration verb] 
cd90: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
cda0: 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  e .** that indic
cdb0: 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74  ates what aspect
cdc0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
cdd0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
cde0: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
cdf0: 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  d..** Subsequent
ce00: 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20   arguments vary 
ce10: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
ce20: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
ce30: 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  erb..**.** ^Call
ce40: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  s to sqlite3_db_
ce50: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20  config() return 
ce60: 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64  SQLITE_OK if and
ce70: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20   only if.** the 
ce80: 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72  call is consider
ce90: 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  ed successful..*
cea0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  /.int sqlite3_db
ceb0: 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
cec0: 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
ced0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
cee0: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
cef0: 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
cf00: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
cf10: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
cf20: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
cf30: 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
cf40: 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
cf50: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
cf60: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
cf70: 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
cf80: 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
cf90: 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
cfa0: 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
cfb0: 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
cfc0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
cfd0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
cfe0: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
cff0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
d000: 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
d010: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d020: 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
d030: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
d040: 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
d050: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
d060: 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
d070: 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
d080: 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
d090: 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
d0a0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
d0b0: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
d0c0: 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
d0d0: 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
d0e0: 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
d0f0: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
d100: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
d110: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d120: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
d130: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
d140: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
d150: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
d160: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
d170: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
d180: 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
d190: 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
d1a0: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
d1b0: 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
d1c0: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
d1d0: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
d1e0: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
d1f0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
d200: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
d210: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
d220: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
d230: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
d240: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
d250: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
d260: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
d270: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
d280: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
d290: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
d2a0: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
d2b0: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
d2c0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
d2d0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
d2e0: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
d2f0: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
d300: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
d310: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
d320: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
d330: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
d340: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
d350: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
d360: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
d370: 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20  alloc and xFree 
d380: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
d390: 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
d3a0: 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
d3b0: 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
d3c0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
d3d0: 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20  library..** The 
d3e0: 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20  xRealloc method 
d3f0: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72  must work like r
d400: 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68  ealloc() from th
d410: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
d420: 72 61 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65  rary.** with the
d430: 20 65 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20   exception that 
d440: 69 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  if the second ar
d450: 67 75 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c  gument to xReall
d460: 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78  oc is zero,.** x
d470: 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20  Realloc must be 
d480: 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73  a no-op - it mus
d490: 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e  t not perform an
d4a0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a  y allocation or.
d4b0: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e  ** deallocation.
d4c0: 20 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e    ^SQLite guaran
d4d0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
d4e0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
d4f0: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
d500: 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
d510: 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
d520: 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
d530: 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69  dup..** And so i
d540: 6e 20 63 61 73 65 73 20 77 68 65 72 65 20 78 52  n cases where xR
d550: 6f 75 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65  oundup always re
d560: 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65  turns a positive
d570: 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61   number,.** xRea
d580: 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d  lloc can perform
d590: 20 65 78 61 63 74 6c 79 20 61 73 20 74 68 65 20   exactly as the 
d5a0: 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79  standard library
d5b0: 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a   realloc() and.*
d5c0: 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f  * still be in co
d5d0: 6d 70 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68  mpliance with th
d5e0: 69 73 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  is specification
d5f0: 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
d600: 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
d610: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
d620: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
d630: 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
d640: 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
d650: 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
d660: 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
d670: 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
d680: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
d690: 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
d6a0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
d6b0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
d6c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
d6d0: 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
d6e0: 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
d6f0: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
d700: 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
d710: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
d720: 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
d730: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
d740: 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
d750: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
d760: 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
d770: 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
d780: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
d790: 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
d7a0: 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
d7b0: 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
d7c0: 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
d7d0: 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
d7e0: 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
d7f0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
d800: 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
d810: 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
d820: 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
d830: 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
d840: 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
d850: 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
d860: 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
d870: 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
d880: 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
d890: 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
d8a0: 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
d8b0: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
d8c0: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
d8d0: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
d8e0: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
d8f0: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
d900: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
d910: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
d920: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
d930: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
d940: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
d950: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
d960: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
d970: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
d980: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d990: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
d9a0: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
d9b0: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
d9c0: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
d9d0: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
d9e0: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
d9f0: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
da00: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
da10: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
da20: 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
da30: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
da40: 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
da50: 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
da60: 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
da70: 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
da80: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
da90: 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
daa0: 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
dab0: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
dac0: 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
dad0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
dae0: 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
daf0: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
db00: 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
db10: 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
db20: 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
db30: 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
db40: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
db50: 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
db60: 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
db70: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
db80: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
db90: 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
dba0: 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
dbb0: 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
dbc0: 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
dbd0: 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
dbe0: 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
dbf0: 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
dc00: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
dc10: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
dc20: 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
dc30: 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
dc40: 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
dc50: 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
dc60: 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
dc70: 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
dc80: 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
dc90: 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
dca0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
dcb0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
dcc0: 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
dcd0: 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
dce0: 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
dcf0: 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
dd00: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
dd10: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
dd20: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
dd30: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
dd40: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
dd50: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
dd60: 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
dd70: 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
dd80: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
dd90: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
dda0: 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
ddb0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
ddc0: 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
ddd0: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
dde0: 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
ddf0: 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
de00: 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
de10: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
de20: 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
de30: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
de40: 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
de50: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
de60: 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
de70: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
de80: 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
de90: 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
dea0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
deb0: 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
dec0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
ded0: 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
dee0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
def0: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
df00: 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
df10: 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
df20: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
df30: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
df40: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
df50: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
df60: 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
df70: 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
df80: 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
df90: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
dfa0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
dfb0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
dfc0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
dfd0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
dfe0: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
dff0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
e000: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
e010: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
e020: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
e030: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e040: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
e050: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
e060: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
e070: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
e080: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
e090: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
e0a0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
e0b0: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
e0c0: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
e0d0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
e0e0: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
e0f0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
e100: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
e110: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
e120: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
e130: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
e140: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e150: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
e160: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
e170: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
e180: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
e190: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
e1a0: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
e1b0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
e1c0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
e1d0: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
e1e0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
e1f0: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
e200: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
e210: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
e220: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
e230: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
e240: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
e250: 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
e260: 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
e270: 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
e280: 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
e290: 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
e2a0: 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
e2b0: 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
e2c0: 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
e2d0: 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
e2e0: 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
e2f0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
e300: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
e310: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
e320: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
e330: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
e340: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
e350: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
e360: 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
e370: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
e380: 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
e390: 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
e3a0: 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
e3b0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e3c0: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
e3d0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
e3e0: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
e3f0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
e400: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
e410: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
e420: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
e430: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e440: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
e450: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
e460: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
e470: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
e480: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
e490: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
e4a0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e4b0: 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
e4c0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
e4d0: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
e4e0: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
e4f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e500: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
e510: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
e520: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
e530: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
e540: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
e550: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
e560: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
e570: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
e580: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e590: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
e5a0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
e5b0: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
e5c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
e5d0: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
e5e0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
e5f0: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
e600: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
e610: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
e620: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
e630: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
e640: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
e650: 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
e660: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
e670: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
e680: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e690: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
e6a0: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
e6b0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
e6c0: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
e6d0: 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
e6e0: 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
e6f0: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
e700: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
e710: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
e720: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
e730: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
e740: 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
e750: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
e760: 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
e770: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
e780: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e790: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
e7a0: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
e7b0: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
e7c0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
e7d0: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
e7e0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
e7f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
e800: 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
e810: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
e820: 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
e830: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
e840: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
e850: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
e860: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
e870: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e880: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
e890: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
e8a0: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
e8b0: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
e8c0: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
e8d0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e8e0: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
e8f0: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
e900: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
e910: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
e920: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
e930: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
e940: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
e950: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
e960: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
e970: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
e980: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
e990: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
e9a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
e9b0: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
e9c0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
e9d0: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
e9e0: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
e9f0: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
ea00: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
ea10: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
ea20: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
ea30: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
ea40: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
ea50: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
ea60: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
ea70: 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
ea80: 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
ea90: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
eaa0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
eab0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
eac0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
ead0: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
eae0: 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
eaf0: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
eb00: 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
eb10: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
eb20: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
eb30: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
eb40: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
eb50: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
eb60: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
eb70: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
eb80: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
eb90: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
eba0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
ebb0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
ebc0: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
ebd0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
ebe0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
ebf0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ec00: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
ec10: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
ec20: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
ec30: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
ec40: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
ec50: 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
ec60: 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
ec70: 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
ec80: 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
ec90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
eca0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
ecb0: 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
ecc0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
ecd0: 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
ece0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
ecf0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
ed00: 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
ed10: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
ed20: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
ed30: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
ed40: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
ed50: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
ed60: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
ed70: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
ed80: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
ed90: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
eda0: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
edb0: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
edc0: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
edd0: 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
ede0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
edf0: 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
ee00: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
ee10: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
ee20: 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
ee30: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
ee40: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
ee50: 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
ee60: 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
ee70: 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
ee80: 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
ee90: 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
eea0: 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
eeb0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
eec0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
eed0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
eee0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
eef0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
ef00: 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
ef10: 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
ef20: 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
ef30: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
ef40: 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
ef50: 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
ef60: 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
ef70: 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
ef80: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ef90: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
efa0: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a   disabled, the .
efb0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  ** following SQL
efc0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
efd0: 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
efe0: 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
eff0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
f000: 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
f010: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
f020: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
f030: 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
f040: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
f050: 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
f060: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
f070: 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
f080: 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
f090: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
f0a0: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
f0b0: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
f0c0: 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
f0d0: 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
f0e0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
f0f0: 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
f100: 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
f110: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
f120: 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
f130: 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
f140: 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
f150: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
f160: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
f170: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
f180: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
f190: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
f1a0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
f1b0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
f1c0: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
f1d0: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
f1e0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
f1f0: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
f200: 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
f210: 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
f220: 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
f230: 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
f240: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
f250: 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
f260: 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
f270: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
f280: 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
f290: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
f2a0: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
f2b0: 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
f2c0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
f2d0: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
f2e0: 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
f2f0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
f300: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
f310: 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
f320: 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
f330: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
f340: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
f350: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
f360: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
f370: 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
f380: 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
f390: 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
f3a0: 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
f3b0: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
f3c0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
f3d0: 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
f3e0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
f3f0: 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
f400: 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
f410: 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
f420: 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
f430: 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
f440: 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
f450: 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
f460: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
f470: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
f480: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
f490: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f4a0: 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
f4b0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f4c0: 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
f4d0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
f4e0: 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
f4f0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f500: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
f510: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
f520: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
f530: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
f540: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
f550: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
f560: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
f570: 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
f580: 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
f590: 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
f5a0: 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a  lemenation.  .**
f5b0: 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
f5c0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ion should not b
f5d0: 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70  e used if an app
f5e0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
f5f0: 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
f600: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
f610: 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
f620: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
f630: 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  CACHE option..**
f640: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
f650: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
f660: 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
f670: 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
f680: 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
f690: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
f6a0: 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
f6b0: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
f6c0: 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
f6d0: 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
f6e0: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
f6f0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
f700: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
f710: 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
f720: 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
f730: 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
f740: 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
f750: 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
f760: 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
f770: 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
f780: 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
f790: 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
f7a0: 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
f7b0: 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
f7c0: 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
f7d0: 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
f7e0: 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
f7f0: 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
f800: 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
f810: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
f820: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
f830: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
f840: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
f850: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
f860: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
f870: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
f880: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
f890: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
f8a0: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
f8b0: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
f8c0: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
f8d0: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
f8e0: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
f8f0: 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
f900: 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
f910: 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
f920: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
f930: 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
f940: 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
f950: 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
f960: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
f970: 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
f980: 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
f990: 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
f9a0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
f9b0: 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
f9c0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
f9d0: 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
f9e0: 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
f9f0: 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
fa00: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
fa10: 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
fa20: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
fa30: 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
fa40: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
fa50: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
fa60: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
fa70: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
fa80: 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
fa90: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
faa0: 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
fab0: 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
fac0: 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
fad0: 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
fae0: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
faf0: 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
fb00: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
fb10: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
fb20: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
fb30: 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
fb40: 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
fb50: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
fb60: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
fb70: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
fb80: 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
fb90: 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
fba0: 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
fbb0: 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
fbc0: 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
fbd0: 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
fbe0: 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
fbf0: 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
fc00: 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
fc10: 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
fc20: 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
fc30: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
fc40: 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
fc50: 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
fc60: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
fc70: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
fc80: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
fc90: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
fca0: 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
fcb0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
fcc0: 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
fcd0: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
fce0: 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
fcf0: 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
fd00: 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
fd10: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
fd20: 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
fd30: 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
fd40: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fd50: 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
fd60: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
fd70: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
fd80: 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
fd90: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
fda0: 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
fdb0: 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
fdc0: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
fdd0: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
fde0: 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
fdf0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
fe00: 63 61 70 70 65 64 20 61 74 20 32 5e 31 32 2e 20  capped at 2^12. 
fe10: 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
fe20: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
fe30: 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
fe40: 73 69 7a 65 20 61 72 65 20 32 5e 35 20 74 68 72  size are 2^5 thr
fe50: 6f 75 67 68 20 32 5e 38 2e 3c 2f 64 64 3e 0a 2a  ough 2^8.</dd>.*
fe60: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
fe70: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
fe80: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
fe90: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
fea0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
feb0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
fec0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
fed0: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
fee0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
fef0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
ff00: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
ff10: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
ff20: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
ff30: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
ff40: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
ff50: 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
ff60: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
ff70: 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
ff80: 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
ff90: 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
ffa0: 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
ffb0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
ffc0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
ffd0: 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
ffe0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
fff0: 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
10000 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
10010 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
10020 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
10030 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
10040 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
10050 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
10060 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
10070 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
10080 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
10090 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
100a0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
100b0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
100c0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
100d0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
100e0 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
100f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
10100 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
10110 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
10120 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
10130 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
10140 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
10150 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
10160 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
10170 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
10180 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
10190 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
101a0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
101b0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
101c0 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
101d0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
101e0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
101f0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
10200 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
10210 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
10220 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
10230 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
10240 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
10250 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
10260 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
10270 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
10280 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
10290 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
102a0 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
102b0 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
102c0 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
102d0 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
102e0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
102f0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10300 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10310 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
10320 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
10330 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10340 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
10350 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
10360 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
10370 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
10380 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
10390 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
103a0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
103b0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
103c0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
103d0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
103e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
103f0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
10400 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
10410 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
10420 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
10430 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
10440 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
10450 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
10460 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
10470 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
10480 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
10490 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
104a0 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
104b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
104c0 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
104d0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
104e0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
104f0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
10500 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
10510 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
10520 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
10530 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
10540 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10550 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
10560 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
10570 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
10580 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
10590 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
105a0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
105b0 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
105c0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
105d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
105e0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
105f0 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
10600 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
10610 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
10620 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
10630 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10640 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
10650 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
10660 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
10670 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
10680 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
10690 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
106a0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
106b0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
106c0 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
106d0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
106e0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
106f0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
10700 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
10710 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
10720 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
10730 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
10740 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
10750 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
10760 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
10770 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
10780 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
10790 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
107a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
107b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
107c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
107d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
107e0 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
107f0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
10800 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
10810 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
10820 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10830 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
10840 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
10850 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10860 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
10870 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
10880 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
10890 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
108a0 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
108b0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
108c0 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
108d0 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
108e0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
108f0 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
10900 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
10910 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
10920 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
10930 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
10940 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
10950 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
10960 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
10970 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
10980 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
10990 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
109a0 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
109b0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
109c0 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
109d0 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
109e0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
109f0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
10a00 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
10a10 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
10a20 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
10a30 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
10a40 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
10a50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
10a60 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
10a70 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
10a80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
10a90 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
10aa0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
10ab0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
10ac0 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
10ad0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
10ae0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
10af0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
10b00 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
10b10 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
10b20 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
10b30 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
10b40 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
10b50 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
10b60 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
10b70 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
10b80 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
10b90 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
10ba0 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
10bb0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
10bc0 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
10bd0 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
10be0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
10bf0 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
10c00 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
10c10 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
10c20 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
10c30 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
10c40 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
10c50 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
10c60 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
10c70 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
10c80 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
10c90 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
10ca0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
10cb0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  . </dd>.**.** </
10cc0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
10cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
10ce0 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
10cf0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
10d00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
10d10 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
10d20 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
10d30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
10d40 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
10d50 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
10d60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10d70 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
10d80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
10d90 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
10da0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10db0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
10dc0 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
10dd0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
10de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
10df0 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
10e00 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
10e10 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
10e20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10e30 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
10e40 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
10e50 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
10e60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10e70 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
10e80 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
10e90 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
10ea0 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
10eb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
10ec0 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
10ed0 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
10ee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
10ef0 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
10f00 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
10f10 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
10f20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10f30 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
10f40 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
10f50 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
10f60 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
10f70 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
10f80 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
10f90 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
10fa0 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
10fb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
10fc0 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
10fd0 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
10fe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
10ff0 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
11000 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   14  /* sqlite3_
11010 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20  pcache_methods* 
11020 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11030 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
11040 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c  HE    15  /* sql
11050 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
11060 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
11070 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11080 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
11090 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
110a0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
110b0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
110c0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
110d0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
110e0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
110f0 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
11100 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
11110 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11120 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
11130 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
11140 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11150 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
11160 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
11170 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
11180 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
11190 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
111a0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
111b0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
111c0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
111d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
111e0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
111f0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
11200 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
11210 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
11220 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
11230 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11240 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
11250 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
11260 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
11270 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
11280 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11290 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
112a0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
112b0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
112c0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
112d0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
112e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
112f0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
11300 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
11310 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
11320 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
11330 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
11340 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
11350 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
11360 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
11370 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
11380 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
11390 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
113a0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
113b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
113c0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
113d0 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
113e0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
113f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
11400 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
11410 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
11420 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
11430 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
11440 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
11450 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11460 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
11470 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
11480 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
11490 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
114a0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
114b0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
114c0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
114d0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
114e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
114f0 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
11500 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
11510 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
11520 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
11530 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
11540 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
11550 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
11560 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
11570 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
11580 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
11590 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
115a0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
115b0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
115c0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
115d0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
115e0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
115f0 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
11600 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
11610 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
11620 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
11630 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
11640 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
11650 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
11660 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
11670 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
11680 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
11690 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
116a0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
116b0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
116c0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
116d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
116e0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
116f0 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
11700 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
11710 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
11720 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
11730 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
11740 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
11750 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
11760 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
11770 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
11780 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
11790 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
117a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
117b0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
117c0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
117d0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
117e0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
117f0 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
11800 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
11810 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
11820 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
11830 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
11840 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
11850 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
11860 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
11870 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
11880 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
11890 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
118a0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
118b0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
118c0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
118d0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
118e0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
118f0 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
11900 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
11910 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
11920 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
11930 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
11940 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
11950 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
11960 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
11970 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
11980 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
11990 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
119a0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
119b0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
119c0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
119d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
119e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
119f0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
11a00 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
11a10 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
11a20 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
11a30 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
11a40 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
11a50 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
11a60 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
11a70 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
11a80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
11a90 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
11aa0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
11ab0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
11ac0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
11ad0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
11ae0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
11af0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
11b00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11b10 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
11b20 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
11b30 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
11b40 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
11b50 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
11b60 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
11b70 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
11b80 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
11b90 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
11ba0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
11bb0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
11bc0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
11bd0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
11be0 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
11bf0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
11c00 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
11c10 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
11c20 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
11c30 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
11c40 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
11c50 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
11c60 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
11c70 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
11c80 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
11c90 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
11ca0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
11cb0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
11cc0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
11cd0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
11ce0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
11cf0 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
11d00 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
11d10 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
11d20 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
11d30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
11d40 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
11d50 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
11d60 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
11d70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
11d80 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
11d90 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
11da0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
11db0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
11dc0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
11dd0 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
11de0 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
11df0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
11e00 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
11e10 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
11e20 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
11e30 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
11e40 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
11e50 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
11e60 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
11e70 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
11e80 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
11e90 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
11ea0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
11eb0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
11ec0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
11ed0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
11ee0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
11ef0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
11f00 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
11f10 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
11f20 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
11f30 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
11f40 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
11f50 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
11f60 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
11f70 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
11f80 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
11f90 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
11fa0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
11fb0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
11fc0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
11fd0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
11fe0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
11ff0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
12000 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
12010 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
12020 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
12030 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
12040 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
12050 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
12060 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
12070 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
12080 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
12090 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
120a0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
120b0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
120c0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
120d0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
120e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
120f0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
12100 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
12110 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
12120 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
12130 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
12140 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12150 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
12160 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
12170 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
12180 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
12190 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
121a0 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
121b0 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
121c0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
121d0 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
121e0 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
121f0 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
12200 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
12210 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
12220 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64   row is returned
12230 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
12240 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
12250 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69  trigger is runni
12260 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
12270 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d  the trigger term
12280 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75  inates, the valu
12290 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
122a0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
122b0 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73  verts to the las
122c0 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64  t value inserted
122d0 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
122e0 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  ger fired.)^.**.
122f0 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
12300 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
12310 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
12320 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
12330 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
12340 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
12350 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
12360 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
12370 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
12380 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
12390 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
123a0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
123b0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
123c0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
123d0 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
123e0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
123f0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
12400 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
12410 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
12420 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
12430 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
12440 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
12450 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
12460 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
12470 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
12480 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
12490 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
124a0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
124b0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
124c0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
124d0 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
124e0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
124f0 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
12500 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
12510 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
12520 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
12530 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
12540 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
12550 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
12560 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
12570 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
12580 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
12590 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
125a0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
125b0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
125c0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
125d0 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
125e0 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
125f0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
12600 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
12610 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
12620 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
12630 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
12640 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
12650 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
12660 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
12670 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
12680 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
12690 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
126a0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
126b0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
126c0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
126d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
126e0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
126f0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
12700 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
12710 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
12720 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
12730 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
12740 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
12750 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
12760 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
12770 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
12780 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
12790 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
127a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
127b0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
127c0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
127d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
127e0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
127f0 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
12800 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
12810 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
12820 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
12830 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
12840 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
12850 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
12860 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
12870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12880 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
12890 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
128a0 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
128b0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
128c0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
128d0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
128e0 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
128f0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
12900 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
12910 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
12920 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
12930 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
12940 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
12950 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
12960 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
12970 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
12980 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
12990 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
129a0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
129b0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
129c0 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
129d0 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
129e0 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
129f0 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
12a00 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
12a10 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
12a20 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
12a30 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
12a40 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
12a50 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
12a60 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
12a70 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
12a80 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
12a90 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
12aa0 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
12ab0 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
12ac0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
12ad0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
12ae0 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
12af0 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
12b00 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
12b10 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
12b20 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
12b30 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
12b40 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
12b50 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
12b60 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
12b70 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
12b80 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
12b90 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
12ba0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
12bb0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
12bc0 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
12bd0 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
12be0 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
12bf0 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
12c00 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
12c10 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
12c20 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
12c30 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
12c40 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
12c50 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
12c60 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
12c70 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
12c80 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
12c90 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
12ca0 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
12cb0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
12cc0 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
12cd0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
12ce0 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
12cf0 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
12d00 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
12d10 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
12d20 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
12d30 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
12d40 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
12d50 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
12d60 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
12d70 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
12d80 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
12d90 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
12da0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
12db0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
12dc0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
12dd0 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
12de0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
12df0 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
12e00 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
12e10 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
12e20 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
12e30 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
12e40 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
12e50 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
12e60 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
12e70 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
12e80 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
12e90 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
12ea0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
12eb0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
12ec0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
12ed0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
12ee0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
12ef0 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
12f00 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
12f10 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
12f20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
12f30 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
12f40 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
12f50 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
12f60 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
12f70 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
12f80 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
12f90 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
12fa0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
12fb0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
12fc0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
12fd0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
12fe0 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
12ff0 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
13000 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
13010 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
13020 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
13030 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
13040 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
13050 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
13060 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
13070 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
13080 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
13090 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
130a0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
130b0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
130c0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
130d0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
130e0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
130f0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
13100 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13110 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
13120 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
13130 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
13140 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
13150 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
13160 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
13170 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
13180 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
13190 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
131a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
131b0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
131c0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
131d0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
131e0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
131f0 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
13200 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
13210 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
13220 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
13230 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
13240 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
13250 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
13260 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
13270 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
13280 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
13290 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
132a0 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
132b0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
132c0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
132d0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
132e0 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
132f0 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
13300 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
13310 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
13320 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
13330 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
13340 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
13350 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
13360 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
13370 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
13380 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
13390 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
133a0 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
133b0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
133c0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
133d0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
133e0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
133f0 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
13400 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
13410 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
13420 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
13430 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
13440 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
13450 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
13460 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
13470 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
13480 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
13490 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
134a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
134b0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
134c0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
134d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
134e0 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
134f0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
13500 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
13510 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
13520 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
13530 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
13540 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
13550 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
13560 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
13570 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
13580 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
13590 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
135a0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
135b0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
135c0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
135d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
135e0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
135f0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
13600 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
13610 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
13620 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
13630 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
13640 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
13650 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
13660 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
13670 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
13680 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
13690 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
136a0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
136b0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
136c0 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
136d0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
136e0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
136f0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
13700 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
13710 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
13720 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
13730 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
13740 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
13750 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
13760 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
13770 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
13780 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
13790 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
137a0 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
137b0 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
137c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
137d0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
137e0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
137f0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
13800 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
13810 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
13820 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
13830 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
13840 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
13850 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
13860 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
13870 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
13880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13890 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
138a0 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
138b0 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
138c0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
138d0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
138e0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
138f0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
13900 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
13910 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
13920 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
13930 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
13940 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
13950 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
13960 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
13970 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
13980 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
13990 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
139a0 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
139b0 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
139c0 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
139d0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
139e0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
139f0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
13a00 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
13a10 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
13a20 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
13a30 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
13a40 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
13a50 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
13a60 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
13a70 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
13a80 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
13a90 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
13aa0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
13ab0 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
13ac0 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
13ad0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
13ae0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
13af0 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
13b00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13b10 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
13b20 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
13b30 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
13b40 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
13b50 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
13b60 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
13b70 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
13b80 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
13b90 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
13ba0 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
13bb0 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
13bc0 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
13bd0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
13be0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
13bf0 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
13c00 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
13c10 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
13c20 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
13c30 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
13c40 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
13c50 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
13c60 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
13c70 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
13c80 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
13c90 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
13ca0 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
13cb0 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
13cc0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
13cd0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
13ce0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
13cf0 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
13d00 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
13d10 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
13d20 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
13d30 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
13d40 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
13d50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
13d60 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
13d70 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
13d80 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
13d90 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
13da0 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
13db0 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
13dc0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
13dd0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
13de0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13df0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
13e00 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
13e10 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
13e20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
13e30 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
13e40 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
13e50 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
13e60 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
13e70 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
13e80 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
13e90 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
13ea0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
13eb0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
13ec0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
13ed0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
13ee0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
13ef0 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
13f00 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
13f10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
13f20 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
13f30 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
13f40 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
13f50 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
13f60 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
13f70 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
13f80 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
13f90 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
13fa0 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
13fb0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
13fc0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
13fd0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
13fe0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
13ff0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
14000 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
14010 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
14020 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
14030 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
14040 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
14050 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
14060 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
14070 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
14080 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
14090 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
140a0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
140b0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
140c0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
140d0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
140e0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
140f0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
14100 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
14110 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
14120 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
14130 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
14140 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
14150 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
14160 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
14170 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
14180 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
14190 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
141a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
141b0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
141c0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
141d0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
141e0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
141f0 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
14200 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
14210 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
14220 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
14230 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
14240 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
14250 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
14260 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
14270 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
14280 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
14290 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
142a0 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
142b0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
142c0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
142d0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
142e0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
142f0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
14300 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
14310 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
14320 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
14330 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
14340 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
14350 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
14360 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
14370 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
14380 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
14390 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
143a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
143b0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
143c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
143d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
143e0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
143f0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
14400 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
14410 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
14420 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
14430 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
14440 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
14450 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
14460 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
14470 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
14480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14490 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
144a0 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
144b0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
144c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
144d0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
144e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
144f0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
14500 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
14510 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
14520 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
14530 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
14540 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
14550 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
14560 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
14570 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
14580 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
14590 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
145a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
145b0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
145c0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
145d0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
145e0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
145f0 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
14600 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
14610 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
14620 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
14630 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
14640 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
14650 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
14660 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
14670 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
14680 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
14690 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
146a0 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
146b0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
146c0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
146d0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
146e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
146f0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
14700 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
14710 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
14720 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
14730 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
14740 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
14750 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
14760 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
14770 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
14780 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
14790 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
147a0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
147b0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
147c0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
147d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
147e0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
147f0 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
14800 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
14810 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
14820 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
14830 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
14840 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
14850 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
14860 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
14870 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
14880 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
14890 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
148a0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
148b0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
148c0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
148d0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
148e0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
148f0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
14900 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
14910 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
14920 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
14930 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
14940 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
14950 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
14960 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
14970 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
14980 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
14990 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
149a0 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
149b0 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
149c0 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
149d0 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
149e0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
149f0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
14a00 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
14a10 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
14a20 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
14a30 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
14a40 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
14a50 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
14a60 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
14a70 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
14a80 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
14a90 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
14aa0 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
14ab0 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
14ac0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
14ad0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
14ae0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
14af0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
14b00 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
14b10 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
14b20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
14b30 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
14b40 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
14b50 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
14b60 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
14b70 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
14b80 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
14b90 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
14ba0 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
14bb0 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
14bc0 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
14bd0 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
14be0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
14bf0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
14c00 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
14c10 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
14c20 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
14c30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
14c40 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
14c50 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
14c60 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
14c70 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
14c80 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
14c90 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
14ca0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
14cb0 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
14cc0 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
14cd0 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
14ce0 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
14cf0 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
14d00 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
14d10 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
14d20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
14d30 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
14d40 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
14d50 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
14d60 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
14d70 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
14d80 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
14d90 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
14da0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
14db0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
14dc0 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
14dd0 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
14de0 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
14df0 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
14e00 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
14e10 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
14e20 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
14e30 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
14e40 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
14e50 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
14e60 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
14e70 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
14e80 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
14e90 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
14ea0 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
14eb0 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
14ec0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
14ed0 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
14ee0 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
14ef0 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
14f00 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
14f10 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
14f20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
14f30 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
14f40 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
14f50 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
14f60 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
14f70 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
14f80 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
14f90 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
14fa0 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
14fb0 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
14fc0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
14fd0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
14fe0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
14ff0 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
15000 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
15010 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
15020 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
15030 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
15040 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
15050 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
15060 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
15070 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
15080 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
15090 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
150a0 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
150b0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
150c0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
150d0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
150e0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
150f0 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
15100 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15110 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
15120 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
15130 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
15140 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
15150 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
15160 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
15170 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
15180 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
15190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
151a0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
151b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
151c0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
151d0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
151e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
151f0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
15200 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
15210 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
15220 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
15230 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
15240 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
15250 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
15260 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
15270 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
15280 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
15290 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
152a0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
152b0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
152c0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
152d0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
152e0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
152f0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
15300 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
15310 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
15320 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
15330 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
15340 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
15350 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
15360 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
15370 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
15380 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
15390 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
153a0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
153b0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
153c0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
153d0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
153e0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
153f0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
15400 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
15410 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
15420 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
15430 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
15440 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
15450 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
15460 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
15470 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
15480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15490 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
154a0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
154b0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
154c0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
154d0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
154e0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
154f0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
15500 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
15510 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
15520 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
15530 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
15540 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
15550 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
15560 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
15570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
15580 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
15590 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
155a0 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
155b0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
155c0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
155d0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
155e0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
155f0 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
15600 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
15610 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
15620 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
15630 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
15640 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
15650 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
15660 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
15670 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
15680 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
15690 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
156a0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
156b0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
156c0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
156d0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
156e0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
156f0 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
15700 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
15710 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
15720 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
15730 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
15740 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
15750 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
15760 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
15770 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
15780 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
15790 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
157a0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
157b0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
157c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
157d0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
157e0 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
157f0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
15800 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
15810 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
15820 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
15830 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
15840 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
15850 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
15860 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
15870 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
15880 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
15890 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
158a0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
158b0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
158c0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
158d0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
158e0 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
158f0 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
15900 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
15910 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
15920 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
15930 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
15940 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
15950 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
15960 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
15970 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
15980 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
15990 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
159a0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
159b0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
159c0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
159d0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
159e0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
159f0 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
15a00 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
15a10 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
15a20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
15a30 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
15a40 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
15a50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
15a60 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
15a70 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
15a80 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
15a90 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
15aa0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
15ab0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
15ac0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
15ad0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
15ae0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
15af0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
15b00 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
15b10 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
15b20 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
15b30 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
15b40 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
15b50 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
15b60 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
15b70 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
15b80 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
15b90 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
15ba0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
15bb0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
15bc0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
15bd0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
15be0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
15bf0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
15c00 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
15c10 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
15c20 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
15c30 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
15c40 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15c50 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
15c60 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
15c70 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
15c80 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
15c90 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
15ca0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
15cb0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
15cc0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
15cd0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
15ce0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
15cf0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
15d00 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
15d10 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
15d20 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15d30 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
15d40 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
15d50 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
15d60 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
15d70 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
15d80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
15d90 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
15da0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
15db0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
15dc0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
15dd0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
15de0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
15df0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
15e00 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
15e10 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
15e20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
15e30 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
15e40 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
15e50 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
15e60 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
15e70 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
15e80 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
15e90 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
15ea0 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
15eb0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
15ec0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
15ed0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
15ee0 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
15ef0 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
15f00 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
15f10 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
15f20 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
15f30 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
15f40 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
15f50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
15f60 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
15f70 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
15f80 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
15f90 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
15fa0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
15fb0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
15fc0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
15fd0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
15fe0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
15ff0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
16000 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
16010 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
16020 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
16030 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
16040 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
16050 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
16060 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
16070 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
16080 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
16090 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
160a0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
160b0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
160c0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
160d0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
160e0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
160f0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
16100 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
16110 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
16120 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
16130 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
16140 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
16150 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
16160 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
16170 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
16180 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
16190 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
161a0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
161b0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
161c0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
161d0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
161e0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
161f0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
16200 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
16210 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
16220 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
16230 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
16240 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
16250 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
16260 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
16270 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
16280 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
16290 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
162a0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
162b0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
162c0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
162d0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
162e0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
162f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
16300 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
16310 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
16320 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
16330 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
16340 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
16350 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
16360 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
16370 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16380 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
16390 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
163a0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
163b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
163c0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
163d0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
163e0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
163f0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
16400 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
16410 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
16420 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
16430 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
16440 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
16450 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
16460 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
16470 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
16480 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
16490 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
164a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
164b0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
164c0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
164d0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
164e0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
164f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
16500 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
16510 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
16520 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
16530 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
16540 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
16550 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
16560 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
16570 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
16580 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
16590 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
165a0 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
165b0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
165c0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
165d0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
165e0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
165f0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
16600 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16610 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
16620 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
16630 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
16640 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
16650 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
16660 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
16670 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
16680 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
16690 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
166a0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
166b0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
166c0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
166d0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
166e0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
166f0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
16700 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
16710 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
16720 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
16730 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
16740 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
16750 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
16760 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
16770 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
16780 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
16790 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
167a0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
167b0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
167c0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
167d0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
167e0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
167f0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
16800 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
16810 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
16820 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
16830 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
16840 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
16850 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
16860 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
16870 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
16880 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
16890 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
168a0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
168b0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
168c0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
168d0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
168e0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
168f0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
16900 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
16910 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
16920 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
16930 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
16940 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
16950 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
16960 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
16970 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
16980 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
16990 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
169a0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
169b0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
169c0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
169d0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
169e0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
169f0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
16a00 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
16a10 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
16a20 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
16a30 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
16a40 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
16a50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
16a60 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
16a70 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
16a80 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
16a90 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
16aa0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
16ab0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
16ac0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
16ad0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
16ae0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
16af0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
16b00 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
16b10 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ull-terminated.*
16b20 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
16b30 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
16b40 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
16b50 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
16b60 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
16b70 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
16b80 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
16b90 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
16ba0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
16bb0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
16bc0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
16bd0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
16be0 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
16bf0 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
16c00 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
16c10 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
16c20 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
16c30 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
16c40 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
16c50 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
16c60 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
16c70 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
16c80 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
16c90 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
16ca0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
16cb0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
16cc0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
16cd0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
16ce0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
16cf0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
16d00 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
16d10 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
16d20 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
16d30 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
16d40 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
16d50 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
16d60 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
16d70 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
16d80 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
16d90 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
16da0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
16db0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
16dc0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
16dd0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
16de0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
16df0 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
16e00 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
16e10 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
16e20 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
16e30 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
16e40 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
16e50 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
16e60 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
16e70 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
16e80 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
16e90 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
16ea0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
16eb0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
16ec0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
16ed0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
16ee0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
16ef0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
16f00 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
16f10 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
16f20 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
16f30 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
16f40 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
16f50 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
16f60 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
16f70 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
16f80 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
16f90 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
16fa0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
16fb0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
16fc0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
16fd0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
16fe0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
16ff0 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
17000 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
17010 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
17020 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
17030 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
17040 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
17050 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
17060 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
17070 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
17080 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
17090 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
170a0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
170b0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
170c0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
170d0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
170e0 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
170f0 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
17100 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
17110 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
17120 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
17130 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
17140 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
17150 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
17160 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
17170 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
17180 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
17190 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
171a0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
171b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
171c0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
171d0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
171e0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
171f0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
17200 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
17210 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
17220 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
17230 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
17240 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
17250 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
17260 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
17270 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
17280 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
17290 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
172a0 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
172b0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
172c0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
172d0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
172e0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
172f0 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
17300 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
17310 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
17320 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
17330 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
17340 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
17350 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
17360 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
17370 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
17380 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
17390 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
173a0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
173b0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
173c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
173d0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
173e0 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
173f0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
17400 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
17410 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
17420 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
17430 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
17440 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
17450 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
17460 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
17470 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
17480 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
17490 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
174a0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
174b0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
174c0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
174d0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
174e0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
174f0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
17500 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
17510 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
17520 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
17530 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
17540 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
17550 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
17560 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
17570 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
17580 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
17590 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
175a0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
175b0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
175c0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
175d0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
175e0 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
175f0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
17600 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17610 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
17620 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
17630 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
17640 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
17650 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
17660 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
17670 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
17680 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
17690 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
176a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
176b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
176c0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
176d0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
176e0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
176f0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
17700 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
17710 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
17720 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
17730 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
17740 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
17750 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
17760 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
17770 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
17780 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
17790 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
177a0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
177b0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
177c0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
177d0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
177e0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
177f0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
17800 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
17810 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
17820 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
17830 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
17840 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
17850 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
17860 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
17870 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
17880 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
17890 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
178a0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
178b0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
178c0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
178d0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
178e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
178f0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
17900 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
17910 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
17920 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
17930 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
17940 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
17950 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
17960 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
17970 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
17980 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
17990 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
179a0 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
179b0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
179c0 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
179d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
179e0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
179f0 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
17a00 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
17a10 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
17a20 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
17a30 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
17a40 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
17a50 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
17a60 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
17a70 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
17a80 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
17a90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
17aa0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
17ab0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
17ac0 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
17ad0 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
17ae0 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
17af0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
17b00 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
17b10 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
17b20 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
17b30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
17b40 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
17b50 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
17b60 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
17b70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
17b80 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
17b90 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
17ba0 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
17bb0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
17bc0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
17bd0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
17be0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
17bf0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
17c00 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
17c10 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
17c20 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
17c30 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
17c40 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
17c50 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
17c60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
17c70 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
17c80 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
17c90 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
17ca0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
17cb0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
17cc0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17cd0 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
17ce0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
17cf0 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
17d00 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
17d10 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
17d20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
17d30 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
17d40 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
17d50 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
17d60 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
17d70 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
17d80 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
17d90 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
17da0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
17db0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
17dc0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
17dd0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
17de0 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
17df0 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
17e00 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
17e10 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
17e20 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
17e30 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
17e40 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
17e50 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
17e60 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
17e70 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
17e80 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
17e90 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
17ea0 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
17eb0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
17ec0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
17ed0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e  d..**.** The Win
17ee0 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
17ef0 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a  e layer calls.**
17f00 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
17f10 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
17f20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
17f30 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
17f40 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
17f50 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
17f60 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
17f70 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
17f80 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
17f90 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
17fa0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
17fb0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
17fc0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
17fd0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61  ocation errors a
17fe0 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
17ff0 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70  .** they are rep
18000 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
18010 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
18020 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
18030 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
18040 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
18050 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
18060 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
18070 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
18080 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
18090 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
180a0 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
180b0 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
180c0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
180d0 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
180e0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
180f0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
18100 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18110 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
18120 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
18130 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
18140 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
18150 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
18160 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
18170 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
18180 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
18190 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
181a0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
181b0 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
181c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
181d0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
181e0 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
181f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
18200 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
18210 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
18220 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
18230 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
18240 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
18250 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
18260 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
18270 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
18280 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
18290 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
182a0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
182b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
182c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
182d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
182e0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
182f0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
18300 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
18310 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
18320 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
18330 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
18340 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
18350 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
18360 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
18370 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
18380 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
18390 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
183a0 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
183b0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
183c0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
183d0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
183e0 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
183f0 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
18400 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
18410 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
18420 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
18430 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
18440 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
18450 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
18460 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
18470 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
18480 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
18490 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
184a0 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
184b0 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
184c0 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
184d0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
184e0 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
184f0 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
18500 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
18510 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
18520 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
18530 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
18540 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
18550 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
18560 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
18570 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
18580 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
18590 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
185a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
185b0 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
185c0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
185d0 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
185e0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
185f0 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
18600 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
18610 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
18620 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
18630 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
18640 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
18650 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
18660 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
18670 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
18680 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
18690 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
186a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
186b0 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
186c0 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
186d0 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
186e0 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
186f0 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
18700 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
18710 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
18720 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
18730 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
18740 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
18750 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
18760 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
18770 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
18780 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
18790 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
187a0 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
187b0 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
187c0 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
187d0 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
187e0 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
187f0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
18800 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
18810 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
18820 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
18830 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
18840 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
18850 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
18860 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
18870 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
18880 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
18890 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
188a0 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
188b0 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e  uffer P..**.** ^
188c0 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
188d0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
188e0 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
188f0 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
18900 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
18910 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
18920 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
18930 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
18940 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
18950 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
18960 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
18970 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
18980 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20  ect..** ^On all 
18990 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
189a0 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
189b0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
189c0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
189d0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
189e0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
189f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
18a00 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
18a10 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
18a20 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
18a30 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
18a40 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
18a50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
18a60 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
18a70 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
18a80 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
18a90 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
18aa0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18ab0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
18ac0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
18ad0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
18ae0 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
18af0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
18b00 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
18b10 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
18b20 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
18b30 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
18b40 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
18b50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
18b60 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
18b70 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
18b80 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
18b90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
18ba0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
18bb0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
18bc0 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
18bd0 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
18be0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
18bf0 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
18c00 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
18c10 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
18c20 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
18c30 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
18c40 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18c50 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
18c60 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
18c70 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
18c80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18c90 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
18ca0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
18cb0 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
18cc0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
18cd0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
18ce0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
18cf0 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
18d00 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
18d10 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
18d20 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
18d30 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
18d40 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
18d50 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
18d60 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
18d70 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
18d80 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
18d90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18da0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
18db0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
18dc0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
18dd0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
18de0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
18df0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
18e00 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
18e10 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
18e20 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
18e30 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
18e40 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
18e50 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
18e60 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
18e70 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
18e80 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
18e90 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
18ea0 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
18eb0 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
18ec0 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
18ed0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
18ee0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
18ef0 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
18f00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
18f10 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
18f20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
18f30 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
18f40 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
18f50 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
18f60 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
18f70 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
18f80 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
18f90 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
18fa0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
18fb0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18fc0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
18fd0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
18fe0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
18ff0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
19000 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
19010 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
19020 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
19030 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
19040 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
19050 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
19060 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
19070 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
19080 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
19090 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
190a0 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
190b0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
190c0 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
190d0 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
190e0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
190f0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
19100 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
19110 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
19120 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
19130 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
19140 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
19150 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
19160 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
19170 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
19180 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
19190 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
191a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
191b0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
191c0 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
191d0 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
191e0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
191f0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
19200 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
19210 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
19220 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
19230 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
19240 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
19250 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
19260 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
19270 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
19280 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
19290 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
192a0 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
192b0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
192c0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
192d0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
192e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
192f0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
19300 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
19310 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
19320 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
19330 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
19340 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
19350 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
19360 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
19370 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
19380 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
19390 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
193a0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
193b0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
193c0 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
193d0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
193e0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
193f0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
19400 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
19410 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
19420 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
19430 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
19440 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
19450 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
19460 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
19470 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
19480 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
19490 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
194a0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
194b0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
194c0 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
194d0 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
194e0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
194f0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
19500 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
19510 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
19520 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
19530 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
19540 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
19550 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
19560 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
19570 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
19580 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
19590 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
195a0 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
195b0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
195c0 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
195d0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
195e0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
195f0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
19600 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
19610 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
19620 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
19630 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
19640 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
19650 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
19660 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
19670 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
19680 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
19690 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
196a0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
196b0 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
196c0 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
196d0 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
196e0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
196f0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
19700 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
19710 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
19720 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
19730 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
19740 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
19750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
19760 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
19770 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
19780 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19790 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
197a0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
197b0 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
197c0 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
197d0 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
197e0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
197f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
19800 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
19810 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
19820 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19830 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
19840 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
19850 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
19860 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19870 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
19880 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19890 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
198a0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
198b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
198c0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
198d0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
198e0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
198f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
19900 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
19910 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
19920 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
19930 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
19940 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
19950 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
19960 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
19970 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
19980 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
19990 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
199a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
199b0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
199c0 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
199d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
199e0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
199f0 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
19a00 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
19a10 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
19a20 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
19a30 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
19a40 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
19a50 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
19a60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
19a70 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
19a80 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
19a90 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
19aa0 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
19ab0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
19ac0 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
19ad0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
19ae0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
19af0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
19b00 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
19b10 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
19b20 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
19b30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
19b40 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
19b50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
19b60 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
19b70 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
19b80 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
19b90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  /.int sqlite3_se
19ba0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
19bb0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
19bc0 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
19bd0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
19be0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
19bf0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
19c00 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
19c10 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
19c20 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
19c30 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
19c40 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
19c50 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
19c60 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
19c70 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
19c80 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
19c90 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
19ca0 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
19cb0 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
19cc0 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
19cd0 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
19ce0 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
19cf0 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
19d00 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
19d10 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
19d20 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
19d30 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
19d40 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
19d50 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
19d60 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
19d70 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
19d80 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
19d90 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
19da0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
19db0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19dc0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
19dd0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
19de0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
19df0 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
19e00 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
19e10 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
19e20 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
19e30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
19e40 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
19e50 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
19e60 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
19e70 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
19e80 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
19e90 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
19ea0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
19eb0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
19ec0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19ed0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
19ee0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
19ef0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
19f00 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
19f10 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
19f20 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
19f30 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
19f40 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
19f50 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
19f60 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
19f70 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
19f80 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
19f90 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
19fa0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
19fb0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
19fc0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
19fd0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
19fe0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
19ff0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1a000 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1a010 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1a020 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1a030 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1a040 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1a050 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1a060 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1a070 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1a080 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a090 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1a0a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1a0b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1a0c0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
1a0d0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
1a0e0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
1a0f0 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
1a100 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1a110 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
1a120 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
1a130 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
1a140 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
1a150 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
1a160 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
1a170 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1a180 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1a190 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1a1a0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1a1b0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
1a1c0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
1a1d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a1e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a1f0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
1a200 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
1a210 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
1a220 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
1a230 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
1a240 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1a250 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1a260 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a270 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
1a280 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
1a290 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1a2a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1a2b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a2c0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1a2d0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
1a2e0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1a2f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1a300 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a310 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1a320 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
1a330 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a340 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1a350 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a360 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
1a370 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
1a380 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1a390 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1a3a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a3b0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
1a3c0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
1a3d0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1a3e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a3f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a400 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
1a410 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
1a420 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1a430 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1a440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1a450 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
1a460 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
1a470 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1a480 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1a490 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1a4a0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
1a4b0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
1a4c0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1a4d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1a4e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1a4f0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
1a500 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
1a510 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1a520 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1a530 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1a540 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1a550 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
1a560 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1a570 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1a580 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1a590 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
1a5a0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
1a5b0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1a5c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1a5d0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1a5e0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
1a5f0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1a600 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1a610 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1a620 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1a630 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
1a640 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1a650 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1a660 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1a670 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1a680 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
1a690 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1a6a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1a6b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a6c0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
1a6d0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
1a6e0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1a6f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1a700 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a710 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
1a720 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
1a730 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1a740 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1a750 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a760 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
1a770 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
1a780 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1a790 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1a7a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a7b0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
1a7c0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
1a7d0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
1a7e0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
1a7f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a800 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
1a810 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
1a820 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a830 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1a840 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a850 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
1a860 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
1a870 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
1a880 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1a890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a8a0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
1a8b0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
1a8c0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
1a8d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a8e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a8f0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
1a900 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
1a910 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1a920 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1a930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1a940 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
1a950 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
1a960 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
1a970 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1a980 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1a990 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1a9a0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
1a9b0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
1a9c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1a9d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
1a9e0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
1a9f0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
1aa00 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
1aa10 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1aa20 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
1aa30 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
1aa40 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
1aa50 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1aa60 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1aa70 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
1aa80 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
1aa90 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
1aaa0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1aab0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1aac0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1aad0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
1aae0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1aaf0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1ab00 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1ab10 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
1ab20 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
1ab30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ab40 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1ab50 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1ab60 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
1ab70 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
1ab80 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1ab90 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
1aba0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
1abb0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
1abc0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
1abd0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1abe0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
1abf0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
1ac00 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
1ac10 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
1ac20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
1ac30 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
1ac40 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
1ac50 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
1ac60 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1ac70 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
1ac80 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
1ac90 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
1aca0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
1acb0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
1acc0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
1acd0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
1ace0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1acf0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1ad00 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1ad10 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1ad20 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
1ad30 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
1ad40 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
1ad50 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
1ad60 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
1ad70 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
1ad80 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1ad90 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1ada0 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
1adb0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
1adc0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
1add0 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
1ade0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
1adf0 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
1ae00 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
1ae10 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1ae20 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
1ae30 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
1ae40 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
1ae50 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
1ae60 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
1ae70 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
1ae80 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
1ae90 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
1aea0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
1aeb0 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
1aec0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1aed0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1aee0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1aef0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1af00 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1af10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1af20 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1af30 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1af40 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1af50 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1af60 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1af70 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1af80 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1af90 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1afa0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1afb0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
1afc0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
1afd0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
1afe0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
1aff0 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
1b000 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
1b010 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
1b020 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
1b030 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
1b040 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
1b050 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
1b060 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
1b070 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
1b080 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
1b090 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
1b0a0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
1b0b0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
1b0c0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
1b0d0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
1b0e0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
1b0f0 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
1b100 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
1b110 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1b120 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
1b130 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1b140 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1b150 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ite..*/.void *sq
1b160 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
1b170 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
1b180 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
1b190 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
1b1a0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1b1b0 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1b1c0 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1b1d0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1b1e0 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1b1f0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1b200 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1b210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b220 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1b230 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
1b240 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
1b250 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1b260 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
1b270 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
1b280 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1b290 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
1b2a0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
1b2b0 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
1b2c0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
1b2d0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1b2e0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1b2f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1b300 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
1b310 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1b320 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
1b330 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1b340 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1b350 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1b360 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1b370 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1b380 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
1b390 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
1b3a0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
1b3b0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
1b3c0 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
1b3d0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
1b3e0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
1b3f0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1b400 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
1b410 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
1b420 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
1b430 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
1b440 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
1b450 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
1b460 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a   callback X..**.
1b470 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
1b480 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1b490 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
1b4a0 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
1b4b0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1b4c0 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
1b4d0 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
1b4e0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
1b4f0 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
1b500 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
1b510 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
1b520 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
1b530 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1b540 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
1b550 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
1b560 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
1b570 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
1b580 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
1b590 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b5a0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1b5b0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1b5c0 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
1b5d0 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
1b5e0 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
1b5f0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
1b600 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
1b610 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
1b620 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
1b630 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
1b640 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
1b650 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
1b660 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1b670 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1b680 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1b690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b6a0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1b6b0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1b6c0 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
1b6d0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1b6e0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1b6f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b700 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1b710 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1b720 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1b730 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1b740 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1b750 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76  ragraph..**.*/.v
1b760 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1b770 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1b780 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1b790 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1b7a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b7b0 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1b7c0 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1b7d0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
1b7e0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
1b7f0 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
1b800 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e  ase file whose n
1b810 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20  ame is given by 
1b820 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
1b830 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
1b840 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1b850 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1b860 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
1b870 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1b880 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1b890 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
1b8a0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1b8b0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
1b8c0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
1b8d0 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
1b8e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1b8f0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
1b900 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
1b910 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
1b920 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1b930 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
1b940 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
1b950 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
1b960 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1b970 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1b980 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1b990 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
1b9a0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
1b9b0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
1b9c0 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
1b9d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
1b9e0 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
1b9f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1ba00 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
1ba10 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
1ba20 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
1ba30 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
1ba40 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
1ba50 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1ba60 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
1ba70 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
1ba80 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
1ba90 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1baa0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
1bab0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
1bac0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
1bad0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
1bae0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
1baf0 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
1bb00 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
1bb10 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
1bb20 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
1bb30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1bb40 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
1bb50 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
1bb60 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
1bb70 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1bb80 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1bb90 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
1bba0 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
1bbb0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1bbc0 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
1bbd0 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
1bbe0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
1bbf0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
1bc00 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
1bc10 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
1bc20 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
1bc30 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
1bc40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bc50 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
1bc60 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
1bc70 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
1bc80 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
1bc90 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
1bca0 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
1bcb0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1bcc0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1bcd0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
1bce0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
1bcf0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
1bd00 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
1bd10 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
1bd20 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
1bd30 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
1bd40 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
1bd50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bd60 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
1bd70 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1bd80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1bd90 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
1bda0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
1bdb0 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
1bdc0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1bdd0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
1bde0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
1bdf0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
1be00 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1be10 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
1be20 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
1be30 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
1be40 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1be50 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
1be60 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
1be70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1be80 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
1be90 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1bea0 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
1beb0 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
1bec0 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1bed0 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
1bee0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1bef0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1bf00 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1bf10 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1bf20 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
1bf30 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1bf40 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1bf50 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1bf60 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1bf70 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
1bf80 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
1bf90 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1bfa0 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1bfb0 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
1bfc0 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
1bfd0 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
1bfe0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1bff0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
1c000 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1c010 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1c020 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1c030 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
1c040 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1c050 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1c060 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1c070 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1c080 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
1c090 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
1c0a0 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1c0b0 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1c0c0 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1c0d0 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1c0e0 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1c0f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1c100 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1c110 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1c120 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1c130 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1c140 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1c150 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1c160 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1c170 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1c180 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   or one of the c
1c190 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1c1a0 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64  n above combined
1c1b0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
1c1c0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1c1d0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1c1e0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20  _FULLMUTEX],.** 
1c1f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1c200 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72  REDCACHE] and/or
1c210 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1c220 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
1c230 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s,.** then the b
1c240 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
1c250 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
1c260 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1c270 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
1c280 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
1c290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c2a0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
1c2b0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
1c2c0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1c2d0 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
1c2e0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
1c2f0 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
1c300 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
1c310 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1c320 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
1c330 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1c340 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1c350 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1c360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c370 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1c380 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1c390 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1c3a0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1c3b0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1c3c0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1c3d0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1c3e0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1c3f0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
1c400 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1c410 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1c420 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c430 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
1c440 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
1c450 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1c460 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
1c470 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1c480 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
1c490 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
1c4a0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1c4b0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1c4c0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
1c4d0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1c4e0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1c4f0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1c500 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
1c510 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
1c520 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
1c530 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
1c540 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
1c550 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
1c560 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
1c570 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
1c580 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
1c590 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1c5a0 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
1c5b0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1c5c0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
1c5d0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1c5e0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1c5f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1c600 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1c610 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1c620 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1c630 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1c640 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1c650 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1c660 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1c670 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1c680 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1c690 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1c6a0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1c6b0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1c6c0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1c6d0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1c6e0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1c6f0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1c700 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1c710 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1c720 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1c730 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
1c740 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1c750 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
1c760 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1c770 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
1c780 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1c790 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
1c7a0 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
1c7b0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
1c7c0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1c7d0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
1c7e0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
1c7f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1c800 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  losed..**.** ^Th
1c810 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1c820 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1c830 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
1c840 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
1c850 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1c860 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
1c870 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1c880 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
1c890 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
1c8a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c8b0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
1c8c0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
1c8d0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
1c8e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1c8f0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
1c900 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1c910 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
1c920 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
1c930 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
1c940 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
1c950 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
1c960 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
1c970 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
1c980 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1c990 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
1c9a0 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
1c9b0 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
1c9c0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
1c9d0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
1c9e0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
1c9f0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
1ca00 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
1ca10 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
1ca20 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
1ca30 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
1ca40 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1ca50 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1ca60 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71  _v2()..*/.int sq
1ca70 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
1ca80 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1ca90 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1caa0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1cab0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1cac0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1cad0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1cae0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1caf0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
1cb00 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
1cb10 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1cb20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1cb30 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
1cb40 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1cb50 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1cb60 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1cb70 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1cb80 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
1cb90 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1cba0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1cbb0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1cbc0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1cbd0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
1cbe0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1cbf0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
1cc00 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
1cc10 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
1cc20 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1cc30 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
1cc40 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
1cc50 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
1cc60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cc70 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
1cc80 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
1cc90 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
1cca0 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
1ccb0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1ccc0 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
1ccd0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
1cce0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1ccf0 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1cd00 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
1cd10 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
1cd20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1cd30 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1cd40 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
1cd50 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
1cd60 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
1cd70 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
1cd80 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
1cd90 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1cda0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
1cdb0 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
1cdc0 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
1cdd0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1cde0 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
1cdf0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
1ce00 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
1ce10 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
1ce20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
1ce30 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
1ce40 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
1ce50 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
1ce60 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
1ce70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1ce80 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
1ce90 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1cea0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
1ceb0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
1cec0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1ced0 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
1cee0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1cef0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
1cf00 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
1cf10 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
1cf20 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
1cf30 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
1cf40 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
1cf50 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1cf60 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
1cf70 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
1cf80 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
1cf90 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
1cfa0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
1cfb0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
1cfc0 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
1cfd0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
1cfe0 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
1cff0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
1d000 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
1d010 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
1d020 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1d030 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
1d040 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
1d050 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
1d060 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
1d070 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
1d080 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
1d090 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
1d0a0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
1d0b0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
1d0c0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
1d0d0 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
1d0e0 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
1d0f0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
1d100 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
1d110 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
1d120 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
1d130 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
1d140 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
1d150 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
1d160 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
1d170 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
1d180 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
1d190 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d1a0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
1d1b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
1d1c0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
1d1d0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
1d1e0 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
1d1f0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
1d200 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
1d210 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
1d220 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1d230 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
1d240 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
1d250 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
1d260 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
1d270 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
1d280 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
1d290 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
1d2a0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
1d2b0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
1d2c0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
1d2d0 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
1d2e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1d2f0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
1d300 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
1d310 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
1d320 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
1d330 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
1d340 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
1d350 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
1d360 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1d370 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1d380 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
1d390 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
1d3a0 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
1d3b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
1d3c0 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
1d3d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d3e0 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
1d3f0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
1d400 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
1d410 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
1d420 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
1d430 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
1d440 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
1d450 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
1d460 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
1d470 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
1d480 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
1d490 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
1d4a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
1d4b0 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
1d4c0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
1d4d0 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
1d4e0 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
1d4f0 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
1d500 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
1d510 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
1d520 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1d530 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
1d540 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
1d550 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1d560 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d570 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
1d580 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
1d590 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
1d5a0 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
1d5b0 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
1d5c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1d5d0 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
1d5e0 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
1d5f0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
1d600 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1d610 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
1d620 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1d630 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
1d640 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1d650 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
1d660 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
1d670 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
1d680 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
1d690 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
1d6a0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
1d6b0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
1d6c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
1d6d0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
1d6e0 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
1d6f0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
1d700 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
1d710 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
1d720 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1d730 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1d740 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
1d750 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
1d760 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1d770 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
1d780 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
1d790 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
1d7a0 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
1d7b0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1d7c0 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
1d7d0 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
1d7e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
1d7f0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
1d800 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1d810 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d820 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
1d830 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
1d840 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
1d850 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1d860 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
1d870 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
1d880 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
1d890 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
1d8a0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1d8b0 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
1d8c0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
1d8d0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
1d8e0 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
1d8f0 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
1d900 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
1d910 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1d920 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1d930 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1d940 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
1d950 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
1d960 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
1d970 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
1d980 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
1d990 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
1d9a0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
1d9b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
1d9c0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d9d0 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
1d9e0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
1d9f0 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
1da00 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
1da10 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1da20 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1da30 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
1da40 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1da50 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1da60 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1da70 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1da80 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1da90 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1daa0 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
1dab0 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
1dac0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1dad0 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
1dae0 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
1daf0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
1db00 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1db10 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
1db20 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
1db30 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
1db40 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
1db50 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
1db60 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
1db70 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
1db80 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
1db90 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
1dba0 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
1dbb0 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
1dbc0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
1dbd0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
1dbe0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
1dbf0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
1dc00 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
1dc10 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1dc20 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
1dc30 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
1dc40 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
1dc50 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
1dc60 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
1dc70 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
1dc80 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
1dc90 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
1dca0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
1dcb0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
1dcc0 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
1dcd0 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
1dce0 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
1dcf0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
1dd00 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
1dd10 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
1dd20 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
1dd30 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
1dd40 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
1dd50 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
1dd60 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
1dd70 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
1dd80 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
1dd90 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
1dda0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
1ddb0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
1ddc0 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
1ddd0 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
1dde0 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
1ddf0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
1de00 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
1de10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
1de20 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
1de30 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
1de40 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
1de50 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
1de60 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
1de70 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
1de80 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
1de90 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
1dea0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
1deb0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
1dec0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1ded0 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
1dee0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
1def0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
1df00 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
1df10 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
1df20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
1df30 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
1df40 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
1df50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1df60 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
1df70 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
1df80 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
1df90 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
1dfa0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
1dfb0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
1dfc0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
1dfd0 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
1dfe0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1dff0 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
1e000 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
1e010 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1e020 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
1e030 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
1e040 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1e050 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
1e060 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
1e070 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
1e080 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
1e090 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
1e0a0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
1e0b0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53   <dl>.** ^(<dt>S
1e0c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1e0d0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1e0e0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
1e0f0 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
1e100 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
1e110 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
1e120 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1e130 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1e140 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1e150 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e160 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
1e170 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
1e180 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
1e190 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1e1a0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
1e1b0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e1c0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1e1d0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
1e1e0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
1e1f0 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
1e200 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
1e210 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
1e220 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1e230 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1e240 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
1e250 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
1e260 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
1e270 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1e280 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1e290 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1e2a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1e2b0 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1e2c0 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1e2d0 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
1e2e0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1e2f0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1e300 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
1e310 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1e320 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
1e330 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
1e340 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
1e350 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1e360 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1e370 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1e380 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1e390 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1e3a0 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1e3b0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1e3c0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1e3d0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1e3e0 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
1e3f0 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
1e400 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
1e410 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
1e420 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
1e430 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
1e440 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
1e450 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
1e460 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1e470 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1e480 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e490 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1e4a0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
1e4b0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
1e4c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1e4d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1e4e0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
1e4f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1e500 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
1e510 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1e520 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
1e530 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1e540 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1e550 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
1e560 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e570 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
1e580 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
1e590 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
1e5a0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
1e5b0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
1e5c0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1e5d0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1e5e0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1e5f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
1e600 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
1e610 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
1e620 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1e630 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  nt.)^.**.** ^(<d
1e640 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
1e650 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
1e660 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e670 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
1e680 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
1e690 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
1e6a0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
1e6b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
1e6c0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1e6d0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
1e6e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
1e6f0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
1e700 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
1e710 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e720 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
1e730 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
1e740 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1e750 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
1e760 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
1e770 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1e780 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1e790 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
1e7a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1e7b0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
1e7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
1e7d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1e7e0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1e7f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
1e800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1e810 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
1e820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
1e830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e840 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1e850 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
1e860 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
1e870 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1e880 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
1e890 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
1e8a0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
1e8b0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
1e8c0 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
1e8d0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
1e8e0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
1e8f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
1e900 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
1e910 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
1e920 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
1e930 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
1e940 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
1e950 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
1e960 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
1e970 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
1e980 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
1e990 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1e9a0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
1e9b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e9c0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
1e9d0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
1e9e0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1e9f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1ea00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1ea10 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
1ea20 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
1ea30 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
1ea40 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
1ea50 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
1ea60 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
1ea70 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
1ea80 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
1ea90 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
1eaa0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
1eab0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
1eac0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
1ead0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1eae0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
1eaf0 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
1eb00 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
1eb10 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
1eb20 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
1eb30 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1eb40 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
1eb50 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
1eb60 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
1eb70 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
1eb80 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
1eb90 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
1eba0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
1ebb0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
1ebc0 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
1ebd0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
1ebe0 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
1ebf0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
1ec00 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
1ec10 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
1ec20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1ec30 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
1ec40 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
1ec50 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
1ec60 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
1ec70 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
1ec80 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
1ec90 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
1eca0 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
1ecb0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
1ecc0 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
1ecd0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
1ece0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
1ecf0 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
1ed00 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
1ed10 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
1ed20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
1ed30 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
1ed40 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
1ed50 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
1ed60 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1ed70 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
1ed80 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
1ed90 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
1eda0 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
1edb0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
1edc0 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
1edd0 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
1ede0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
1edf0 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
1ee00 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
1ee10 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
1ee20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1ee30 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
1ee40 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
1ee50 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
1ee60 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
1ee70 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
1ee80 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
1ee90 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
1eea0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
1eeb0 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
1eec0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
1eed0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
1eee0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1eef0 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
1ef00 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
1ef10 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
1ef20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
1ef30 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
1ef40 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
1ef50 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
1ef60 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
1ef70 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
1ef80 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
1ef90 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
1efa0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
1efb0 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
1efc0 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
1efd0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
1efe0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
1eff0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
1f000 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
1f010 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
1f020 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1f030 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
1f040 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1f050 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
1f060 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
1f070 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
1f080 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1f090 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
1f0a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1f0b0 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
1f0c0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
1f0d0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1f0e0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
1f0f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f100 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
1f110 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
1f120 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
1f130 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
1f140 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
1f150 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
1f160 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
1f170 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
1f180 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1f190 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
1f1a0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
1f1b0 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
1f1c0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
1f1d0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
1f1e0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
1f1f0 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
1f200 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1f210 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
1f220 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
1f230 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
1f240 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
1f250 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
1f260 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
1f270 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
1f280 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
1f290 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
1f2a0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
1f2b0 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
1f2c0 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
1f2d0 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
1f2e0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
1f2f0 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
1f300 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
1f310 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
1f320 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
1f330 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
1f340 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
1f350 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
1f360 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a   run it again..*
1f370 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1f380 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
1f390 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
1f3a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1f3b0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
1f3c0 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
1f3d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
1f3e0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
1f3f0 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
1f400 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1f410 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
1f420 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1f430 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1f440 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
1f450 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1f460 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
1f470 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
1f480 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
1f490 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
1f4a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1f4b0 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
1f4c0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
1f4d0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
1f4e0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
1f4f0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
1f500 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
1f510 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
1f520 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
1f530 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
1f540 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
1f550 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1f560 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
1f570 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
1f580 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
1f590 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
1f5a0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
1f5b0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
1f5c0 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
1f5d0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
1f5e0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
1f5f0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
1f600 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
1f610 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
1f620 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
1f630 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
1f640 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
1f650 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
1f660 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
1f670 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
1f680 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
1f690 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1f6a0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
1f6b0 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
1f6c0 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
1f6d0 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
1f6e0 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
1f6f0 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
1f700 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
1f710 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
1f720 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
1f730 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
1f740 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
1f750 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
1f760 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
1f770 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
1f780 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
1f790 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
1f7a0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
1f7b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
1f7c0 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69  BLE_STAT2] compi
1f7d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
1f7e0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68  s enabled..** th
1f7f0 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  e .** </li>.** <
1f800 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
1f810 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
1f820 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1f830 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1f840 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1f850 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1f860 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1f870 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
1f880 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1f890 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1f8a0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1f8b0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1f8c0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1f8d0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1f8e0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1f8f0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1f900 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
1f910 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1f920 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1f930 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1f940 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1f950 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f960 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1f970 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1f980 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1f990 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1f9a0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1f9b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1f9c0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1f9d0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1f9e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1f9f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1fa00 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1fa10 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1fa20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1fa30 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1fa40 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1fa50 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1fa60 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1fa70 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1fa80 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1fa90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1faa0 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
1fab0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1fac0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1fad0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1fae0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1faf0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1fb00 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1fb10 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1fb20 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1fb30 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1fb40 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1fb50 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1fb60 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1fb70 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1fb80 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1fb90 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1fba0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1fbb0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1fbc0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1fbd0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1fbe0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1fbf0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1fc00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1fc10 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1fc20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1fc30 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1fc40 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1fc50 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1fc60 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1fc70 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1fc80 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1fc90 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1fca0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1fcb0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1fcc0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1fcd0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1fce0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1fcf0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1fd00 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1fd10 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1fd20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fd30 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
1fd40 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
1fd50 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
1fd60 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
1fd70 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
1fd80 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
1fd90 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
1fda0 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
1fdb0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1fdc0 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
1fdd0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
1fde0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
1fdf0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
1fe00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1fe10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fe20 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
1fe30 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1fe40 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
1fe50 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
1fe60 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1fe70 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1fe80 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
1fe90 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
1fea0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1feb0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
1fec0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1fed0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
1fee0 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
1fef0 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
1ff00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
1ff10 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
1ff20 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
1ff30 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
1ff40 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
1ff50 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
1ff60 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
1ff70 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1ff80 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
1ff90 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
1ffa0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
1ffb0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
1ffc0 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
1ffd0 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
1ffe0 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
1fff0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
20000 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
20010 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
20020 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
20030 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
20040 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
20050 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
20060 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
20070 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
20080 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
20090 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
200a0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
200b0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
200c0 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
200d0 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
200e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
200f0 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
20100 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
20110 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
20120 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
20130 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
20140 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
20150 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
20160 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
20170 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
20180 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
20190 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
201a0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
201b0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
201c0 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
201d0 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
201e0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
201f0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
20200 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
20210 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
20220 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
20230 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
20240 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
20250 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
20260 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
20270 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
20280 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
20290 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
202a0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
202b0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
202c0 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
202d0 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
202e0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
202f0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
20300 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
20310 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
20320 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
20330 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
20340 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
20350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
20360 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
20370 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
20380 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
20390 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
203a0 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20  on disk..*/.int 
203b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
203c0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
203d0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
203e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
203f0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
20400 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
20410 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
20420 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20430 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
20440 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
20450 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
20460 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
20470 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
20480 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
20490 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
204a0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
204b0 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
204c0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
204d0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
204e0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
204f0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
20500 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
20510 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
20520 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
20530 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
20540 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
20550 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
20560 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
20570 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
20580 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
20590 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
205a0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
205b0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
205c0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
205d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
205e0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
205f0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
20600 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
20610 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
20620 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20630 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
20640 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
20650 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
20660 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
20670 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
20680 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
20690 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
206a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
206b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
206c0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
206d0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
206e0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
206f0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
20700 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
20710 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
20720 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
20730 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
20740 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
20750 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
20760 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
20770 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
20780 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
20790 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
207a0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
207b0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
207c0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
207d0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
207e0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
207f0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
20800 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
20810 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
20820 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
20830 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
20840 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
20850 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
20860 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
20870 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
20880 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
20890 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
208a0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
208b0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
208c0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
208d0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
208e0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
208f0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
20900 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
20910 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
20920 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
20930 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
20940 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
20950 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
20960 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
20970 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
20980 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
20990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
209a0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
209b0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
209c0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
209d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
209e0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
209f0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
20a00 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
20a10 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
20a20 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
20a30 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
20a40 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
20a50 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
20a60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20a70 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
20a80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
20a90 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
20aa0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
20ab0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
20ac0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
20ad0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
20ae0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
20af0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
20b00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20b10 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
20b20 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
20b30 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
20b40 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
20b50 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
20b60 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
20b70 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
20b80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
20b90 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
20ba0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
20bb0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
20bc0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
20bd0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
20be0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
20bf0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
20c00 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
20c10 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
20c20 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
20c30 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
20c40 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
20c50 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
20c60 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
20c70 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
20c80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
20c90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
20ca0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
20cb0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
20cc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
20cd0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
20ce0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
20cf0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
20d00 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
20d10 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
20d20 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
20d30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
20d40 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
20d50 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
20d60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
20d70 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
20d80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
20d90 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
20da0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
20db0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
20dc0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
20dd0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
20de0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
20df0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
20e00 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
20e10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
20e20 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
20e30 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
20e40 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
20e50 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
20e60 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
20e70 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
20e80 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
20e90 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
20ea0 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
20eb0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
20ec0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
20ed0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
20ee0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
20ef0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
20f00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
20f10 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
20f20 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
20f30 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
20f40 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
20f50 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
20f60 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
20f70 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
20f80 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
20f90 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
20fa0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
20fb0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
20fc0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
20fd0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
20fe0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
20ff0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
21000 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
21010 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
21020 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
21030 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
21040 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
21050 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
21060 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
21070 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
21080 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
21090 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
210a0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
210b0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
210c0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
210d0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
210e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
210f0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
21100 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
21110 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
21120 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
21130 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
21140 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
21150 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
21160 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21170 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
21180 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
21190 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
211a0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
211b0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
211c0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
211d0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
211e0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
211f0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
21200 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
21210 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
21220 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
21230 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
21240 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
21250 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
21260 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
21270 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
21280 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
21290 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
212a0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
212b0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
212c0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
212d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
212e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
212f0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
21300 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
21310 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
21320 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
21330 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
21340 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
21350 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
21360 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
21370 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
21380 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
21390 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
213a0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
213b0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
213c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
213d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
213e0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
213f0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
21400 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
21410 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
21420 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
21430 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
21440 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
21450 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
21460 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
21470 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
21480 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
21490 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
214a0 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
214b0 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
214c0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
214d0 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
214e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
214f0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
21500 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
21510 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
21520 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
21530 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
21540 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
21550 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
21560 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
21570 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
21580 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
21590 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
215a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
215b0 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
215c0 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
215d0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
215e0 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
215f0 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
21600 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
21610 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
21620 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
21630 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
21640 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
21650 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
21660 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  l to sqlite3_bin
21670 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c  d_blob(),.** sql
21680 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
21690 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  , or sqlite3_bin
216a0 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73  d_text16() fails
216b0 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .  .** ^If the f
216c0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
216d0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
216e0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
216f0 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
21700 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
21710 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
21720 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
21730 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
21740 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
21750 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
21760 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
21770 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
21780 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
21790 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
217a0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
217b0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
217c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
217d0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
217e0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
217f0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
21800 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
21810 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
21820 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
21830 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
21840 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
21850 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
21860 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
21870 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
21880 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
21890 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
218a0 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
218b0 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
218c0 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
218d0 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
218e0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
218f0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
21900 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
21910 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
21920 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
21930 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
21940 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
21950 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
21960 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
21970 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
21980 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
21990 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
219a0 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
219b0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
219c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
219d0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
219e0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
219f0 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
21a00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
21a10 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
21a20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21a30 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
21a40 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
21a50 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
21a60 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
21a70 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
21a80 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
21a90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
21aa0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
21ab0 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
21ac0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
21ad0 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
21ae0 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
21af0 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
21b00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21b10 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
21b20 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
21b30 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
21b40 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
21b50 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
21b60 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
21b70 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
21b80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
21b90 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
21ba0 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
21bb0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
21bc0 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
21bd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
21be0 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
21bf0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
21c00 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
21c10 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
21c20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
21c30 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
21c40 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
21c50 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
21c60 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
21c70 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
21c80 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
21c90 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
21ca0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
21cb0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
21cc0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
21cd0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21ce0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
21cf0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21d00 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
21d10 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
21d20 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
21d30 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
21d40 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
21d50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
21d60 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
21d70 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
21d80 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
21d90 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
21da0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21db0 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
21dc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
21dd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21de0 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
21df0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
21e00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21e10 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
21e20 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
21e30 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
21e40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
21e50 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21e60 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
21e70 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
21e80 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
21e90 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
21ea0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
21eb0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
21ec0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
21ed0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
21ee0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
21ef0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
21f00 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
21f10 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
21f20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
21f30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21f40 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
21f50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
21f60 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
21f70 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
21f80 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
21f90 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
21fa0 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
21fb0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
21fc0 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
21fd0 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
21fe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21ff0 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
22000 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
22010 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
22020 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
22030 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
22040 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
22050 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
22060 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
22070 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
22080 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
22090 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
220a0 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
220b0 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
220c0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
220d0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
220e0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
220f0 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
22100 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
22110 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
22120 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
22130 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
22140 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
22150 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
22160 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
22170 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
22180 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
22190 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
221a0 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
221b0 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
221c0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
221d0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
221e0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
221f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22200 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
22210 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
22220 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
22230 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
22240 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22250 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
22260 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
22270 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
22280 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
22290 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68  ameter.**.** ^Th
222a0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
222b0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
222c0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
222d0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
222e0 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
222f0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
22300 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22310 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
22320 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
22330 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
22340 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
22350 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
22360 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
22370 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
22380 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
22390 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
223a0 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
223b0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
223c0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
223d0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
223e0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
223f0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
22400 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
22410 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
22420 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
22430 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
22440 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
22450 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
22460 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
22470 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
22480 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
22490 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
224a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
224b0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
224c0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
224d0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
224e0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
224f0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
22500 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
22510 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
22520 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
22530 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
22540 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
22550 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
22560 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
22570 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
22580 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
22590 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
225a0 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
225b0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
225c0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
225d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
225e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
225f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
22600 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22610 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
22620 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
22630 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
22640 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
22650 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
22660 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
22670 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
22680 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
22690 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
226a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
226b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
226c0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
226d0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
226e0 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20  iven Name.**.** 
226f0 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
22700 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
22710 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
22720 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
22730 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
22740 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
22750 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
22760 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
22770 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
22780 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
22790 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
227a0 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
227b0 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
227c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
227d0 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
227e0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
227f0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
22800 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
22810 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
22820 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
22830 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
22840 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
22850 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
22860 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
22870 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
22880 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
22890 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
228a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
228b0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
228c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
228d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
228e0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
228f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22900 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
22910 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
22920 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
22930 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
22940 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
22950 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
22960 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
22970 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
22980 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
22990 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
229a0 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
229b0 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
229c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
229d0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
229e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
229f0 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
22a00 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
22a10 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
22a20 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
22a30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
22a40 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
22a50 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
22a60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
22a70 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
22a80 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
22a90 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
22aa0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
22ab0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
22ac0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
22ad0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
22ae0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
22af0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
22b00 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
22b10 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
22b20 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
22b30 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
22b40 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
22b50 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
22b60 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
22b70 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
22b80 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
22b90 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
22ba0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
22bb0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
22bc0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
22bd0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
22be0 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
22bf0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
22c00 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
22c10 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
22c20 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
22c30 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
22c40 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
22c50 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
22c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22c70 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
22c80 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
22c90 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
22ca0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
22cb0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
22cc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
22cd0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
22ce0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
22cf0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
22d00 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
22d10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
22d20 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
22d30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
22d40 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
22d50 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
22d60 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
22d70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
22d80 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
22d90 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
22da0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
22db0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
22dc0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
22dd0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
22de0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
22df0 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
22e00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
22e10 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
22e20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22e30 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
22e40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
22e50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
22e60 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
22e70 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
22e80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22e90 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
22ea0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
22eb0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
22ec0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
22ed0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
22ee0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
22ef0 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
22f00 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
22f10 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
22f20 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
22f30 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
22f40 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
22f50 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
22f60 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
22f70 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
22f80 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
22f90 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
22fa0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
22fb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
22fc0 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
22fd0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
22fe0 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
22ff0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
23000 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
23010 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
23020 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
23030 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
23040 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
23050 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
23060 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
23070 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
23080 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
23090 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
230a0 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
230b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
230c0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
230d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
230e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
230f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
23100 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
23110 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
23120 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
23130 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
23140 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
23150 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
23160 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
23170 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
23180 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
23190 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
231a0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
231b0 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
231c0 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
231d0 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
231e0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
231f0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
23200 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
23210 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
23220 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
23230 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
23240 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
23250 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
23260 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
23270 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
23280 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
23290 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
232a0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
232b0 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
232c0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
232d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
232e0 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
232f0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
23300 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
23310 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
23320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23330 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
23340 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
23350 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
23360 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
23370 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
23380 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
23390 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
233a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
233b0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
233c0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
233d0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
233e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
233f0 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
23400 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
23410 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
23420 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
23430 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
23440 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
23450 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
23460 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
23470 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
23480 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
23490 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
234a0 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
234b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
234c0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
234d0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
234e0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
234f0 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
23500 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
23510 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
23520 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
23530 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
23540 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
23550 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
23560 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
23570 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
23580 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
23590 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
235a0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
235b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
235c0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
235d0 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
235e0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
235f0 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
23600 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
23610 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
23620 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
23630 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
23640 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
23650 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
23660 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
23670 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
23680 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
23690 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
236a0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
236b0 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
236c0 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
236d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
236e0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
236f0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
23700 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
23710 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
23720 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
23730 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
23740 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
23750 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
23760 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
23770 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
23780 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
23790 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
237a0 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
237b0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
237c0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
237d0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
237e0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
237f0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
23800 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
23810 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
23820 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
23830 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
23840 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
23850 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
23860 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
23870 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
23880 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
23890 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
238a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
238b0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
238c0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
238d0 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
238e0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
238f0 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
23900 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
23910 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
23920 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
23930 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
23940 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
23950 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
23960 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
23970 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
23980 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
23990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
239a0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
239b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
239c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
239d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
239e0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
239f0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
23a00 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
23a10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
23a20 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
23a30 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
23a40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
23a50 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
23a60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
23a70 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
23a80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23a90 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
23aa0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23ab0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
23ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
23ad0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
23ae0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
23af0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
23b00 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
23b10 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
23b20 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
23b30 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
23b40 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
23b50 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
23b60 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
23b70 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
23b80 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
23b90 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
23ba0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
23bb0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
23bc0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
23bd0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
23be0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
23bf0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
23c00 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
23c10 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
23c20 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
23c30 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
23c40 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
23c50 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
23c60 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
23c70 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
23c80 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
23c90 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
23ca0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
23cb0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
23cc0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
23cd0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
23ce0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
23cf0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
23d00 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
23d10 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
23d20 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
23d30 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
23d40 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
23d50 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
23d60 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
23d70 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
23d80 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
23d90 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
23da0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
23db0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
23dc0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
23dd0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
23de0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
23df0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
23e00 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
23e10 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
23e20 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
23e30 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
23e40 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
23e50 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
23e60 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
23e70 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
23e80 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
23e90 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
23ea0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
23eb0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
23ec0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
23ed0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
23ee0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
23ef0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
23f00 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
23f10 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
23f20 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
23f30 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
23f40 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
23f50 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
23f60 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
23f70 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
23f80 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
23f90 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
23fa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
23fb0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
23fc0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23fd0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
23fe0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
23ff0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24000 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
24010 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
24020 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
24030 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
24040 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
24050 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
24060 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24070 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
24080 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
24090 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
240a0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
240b0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
240c0 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
240d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
240e0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
240f0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
24100 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
24110 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
24120 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
24130 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
24140 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
24150 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
24160 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
24170 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
24180 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
24190 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
241a0 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
241b0 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
241c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
241d0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
241e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
241f0 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
24200 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
24210 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
24220 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
24230 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24240 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
24250 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
24260 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
24270 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
24280 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
24290 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
242a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
242b0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
242c0 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
242d0 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
242e0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
242f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
24300 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
24310 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
24320 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
24330 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
24340 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
24350 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
24360 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
24370 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
24380 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
24390 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
243a0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
243b0 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
243c0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
243d0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
243e0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
243f0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
24400 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
24410 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
24420 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
24430 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
24440 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
24450 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
24460 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
24470 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
24480 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
24490 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
244a0 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
244b0 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
244c0 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
244d0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
244e0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
244f0 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
24500 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
24510 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
24520 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
24530 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
24540 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
24550 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
24560 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
24570 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
24580 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
24590 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
245a0 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
245b0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
245c0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
245d0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
245e0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
245f0 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
24600 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
24610 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
24620 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
24630 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
24640 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
24650 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
24660 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
24670 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
24680 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
24690 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
246a0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
246b0 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
246c0 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
246d0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
246e0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
246f0 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
24700 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
24710 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
24720 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
24730 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
24740 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
24750 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
24760 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
24770 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
24780 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
24790 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
247a0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
247b0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
247c0 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
247d0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
247e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
247f0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
24800 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
24810 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
24820 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
24830 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
24840 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
24850 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
24860 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
24870 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
24880 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
24890 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
248a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
248b0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
248c0 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
248d0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
248e0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
248f0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
24900 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
24910 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
24920 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24930 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
24940 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
24950 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
24960 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
24970 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
24980 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
24990 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
249a0 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
249b0 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
249c0 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
249d0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
249e0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
249f0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
24a00 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
24a10 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
24a20 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
24a30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24a40 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
24a50 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
24a60 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
24a70 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
24a80 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
24a90 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
24aa0 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
24ab0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
24ac0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
24ad0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
24ae0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
24af0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
24b00 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
24b10 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
24b20 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f  * For all versio
24b30 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20  ns of SQLite up 
24b40 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67  to and including
24b50 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c   3.6.23.1, a cal
24b60 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
24b70 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65  _reset()] was re
24b80 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c  quired after sql
24b90 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75  ite3_step() retu
24ba0 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a  rned anything.**
24bb0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
24bc0 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20  ITE_ROW] before 
24bd0 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
24be0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
24bf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
24c00 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65   Failure to rese
24c10 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
24c20 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a  tatement using .
24c30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
24c40 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c  t()] would resul
24c50 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  t in an [SQLITE_
24c60 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66  MISUSE] return f
24c70 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  rom.** sqlite3_s
24c80 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65  tep().  But afte
24c90 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33  r version 3.6.23
24ca0 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .1, sqlite3_step
24cb0 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c  () began.** call
24cc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
24cd0 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61  et()] automatica
24ce0 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
24cf0 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a  umstance rather.
24d00 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e  ** than returnin
24d10 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  g [SQLITE_MISUSE
24d20 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20  ].  This is not 
24d30 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d  considered a com
24d40 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72  patibility.** br
24d50 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20  eak because any 
24d60 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
24d70 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61   ever receives a
24d80 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
24d90 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b  error.** is brok
24da0 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e  en by definition
24db0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
24dc0 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63  MIT_AUTORESET] c
24dd0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
24de0 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  on.** can be use
24df0 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65  d to restore the
24e00 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
24e10 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
24e20 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
24e30 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
24e40 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
24e50 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
24e60 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
24e70 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
24e80 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
24e90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
24ea0 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
24eb0 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
24ec0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
24ed0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
24ee0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
24ef0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
24f00 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
24f10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
24f20 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
24f30 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
24f40 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
24f50 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
24f60 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
24f70 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
24f80 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
24f90 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
24fa0 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
24fb0 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
24fc0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
24fd0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
24fe0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
24ff0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
25000 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
25010 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
25020 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
25030 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
25040 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
25050 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
25060 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
25070 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
25080 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
25090 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
250a0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
250b0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
250c0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
250d0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
250e0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
250f0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
25100 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
25110 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
25120 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
25130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
25140 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25150 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
25160 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
25170 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
25180 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
25190 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
251a0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
251b0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
251c0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
251d0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
251e0 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
251f0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
25200 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
25210 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
25220 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
25230 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
25240 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
25250 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
25260 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
25270 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
25280 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
25290 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
252a0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
252b0 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
252c0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
252d0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
252e0 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
252f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
25300 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  er..**.** See al
25310 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
25320 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
25330 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
25340 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
25350 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
25360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
25370 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
25380 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
25390 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
253a0 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
253b0 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
253c0 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
253d0 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
253e0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
253f0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
25400 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
25410 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
25420 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
25430 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
25440 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
25450 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
25460 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
25470 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
25480 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
25490 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
254a0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
254b0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
254c0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
254d0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
254e0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
254f0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
25500 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
25510 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
25520 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
25530 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
25540 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
25550 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
25560 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
25570 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
25580 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
25590 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
255a0 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
255b0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
255c0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
255d0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
255e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
255f0 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
25600 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
25610 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
25620 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
25630 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
25640 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
25650 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
25660 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25670 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
25680 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
25690 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
256a0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
256b0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
256c0 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
256d0 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
256e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
256f0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
25700 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
25710 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
25720 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
25730 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
25740 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
25750 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
25760 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
25770 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
25780 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
25790 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
257a0 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
257b0 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
257c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
257d0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
257e0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
257f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
25800 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
25810 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
25820 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
25830 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
25840 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
25850 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
25860 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
25870 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
25880 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
25890 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
258a0 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
258b0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
258c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
258d0 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
258e0 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
258f0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
25900 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
25910 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
25920 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
25930 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
25940 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
25950 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
25960 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
25970 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
25980 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
25990 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
259a0 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
259b0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
259c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
259d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
259e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
259f0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
25a00 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
25a10 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
25a20 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
25a30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
25a40 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
25a50 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
25a60 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
25a70 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
25a80 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
25a90 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
25aa0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
25ab0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
25ac0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
25ad0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
25ae0 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
25af0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
25b00 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
25b10 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
25b20 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
25b30 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
25b40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
25b50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
25b60 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
25b70 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
25b80 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
25b90 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
25ba0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
25bb0 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
25bc0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
25bd0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
25be0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
25bf0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
25c00 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
25c10 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
25c20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
25c30 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
25c40 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
25c50 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
25c60 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
25c70 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
25c80 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
25c90 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
25ca0 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
25cb0 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
25cc0 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
25cd0 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
25ce0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
25cf0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
25d00 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
25d10 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
25d20 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
25d30 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
25d40 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
25d50 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
25d60 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
25d70 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
25d80 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
25d90 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
25da0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
25db0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
25dc0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
25dd0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
25de0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
25df0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
25e00 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
25e10 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
25e20 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
25e30 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
25e40 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
25e50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
25e60 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
25e70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
25e80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
25e90 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
25ea0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
25eb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
25ec0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
25ed0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
25ee0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
25ef0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
25f00 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
25f10 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
25f20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
25f30 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
25f40 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
25f50 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
25f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25f70 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
25f80 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
25f90 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
25fa0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
25fb0 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
25fc0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
25fd0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
25fe0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
25ff0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
26000 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
26010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26020 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
26030 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
26040 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
26050 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
26060 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
26070 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
26080 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
26090 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
260a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
260b0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
260c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
260d0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
260e0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
260f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26100 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
26110 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
26120 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
26130 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
26140 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
26150 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
26160 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
26170 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
26180 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
26190 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
261a0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
261b0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
261c0 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
261d0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
261e0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
261f0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
26200 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
26210 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
26220 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
26230 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
26240 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
26250 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
26260 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
26270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26280 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
26290 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
262a0 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
262b0 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
262c0 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
262d0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
262e0 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
262f0 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
26300 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
26310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
26320 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
26330 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26340 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
26350 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
26360 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
26370 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
26380 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
26390 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
263a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
263b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
263c0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
263d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
263e0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
263f0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
26400 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
26410 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
26420 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
26430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
26440 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
26450 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
26460 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
26470 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
26480 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
26490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
264a0 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
264b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
264c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
264d0 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
264e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
264f0 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
26500 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
26510 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
26520 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
26530 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
26540 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
26550 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
26560 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26570 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
26580 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
26590 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
265a0 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
265b0 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
265c0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
265d0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
265e0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
265f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
26600 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
26610 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
26620 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
26630 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
26640 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
26650 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
26660 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
26670 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
26680 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
26690 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
266a0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
266b0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
266c0 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
266d0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
266e0 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
266f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
26700 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
26710 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
26720 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
26730 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
26740 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
26750 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
26760 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
26770 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
26780 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
26790 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
267a0 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
267b0 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
267c0 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
267d0 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
267e0 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
267f0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
26800 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
26810 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
26820 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
26830 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
26840 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
26850 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
26860 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
26870 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
26880 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
26890 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
268a0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
268b0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
268c0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
268d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
268e0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
268f0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
26900 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
26910 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
26920 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
26930 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
26940 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
26950 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
26960 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
26970 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
26980 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
26990 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
269a0 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
269b0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
269c0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
269d0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
269e0 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
269f0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
26a00 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
26a10 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
26a20 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
26a30 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
26a40 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
26a50 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
26a60 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
26a70 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
26a80 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
26a90 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
26aa0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
26ab0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
26ac0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
26ad0 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
26ae0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
26af0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
26b00 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
26b10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
26b20 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
26b30 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
26b40 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
26b50 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
26b60 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
26b70 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
26b80 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
26b90 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
26ba0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
26bb0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
26bc0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
26bd0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
26be0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
26bf0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
26c00 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
26c10 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
26c20 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
26c30 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
26c40 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
26c50 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
26c60 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
26c70 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
26c80 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
26c90 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
26ca0 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
26cb0 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
26cc0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
26cd0 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
26ce0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
26cf0 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
26d00 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
26d10 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
26d20 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
26d30 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
26d40 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
26d50 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
26d60 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
26d70 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
26d80 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
26d90 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
26da0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
26db0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
26dc0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
26dd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
26de0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
26df0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
26e00 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
26e10 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
26e20 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
26e30 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
26e40 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
26e50 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
26e60 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
26e70 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
26e80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26e90 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
26ea0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
26eb0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
26ec0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
26ed0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
26ee0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
26ef0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
26f00 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
26f10 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
26f20 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
26f30 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
26f40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
26f50 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
26f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26f70 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
26f80 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
26f90 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
26fa0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
26fb0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
26fc0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
26fd0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
26fe0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
26ff0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
27000 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
27010 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
27020 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
27030 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
27040 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
27050 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
27060 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
27070 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
27080 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
27090 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
270a0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
270b0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
270c0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
270d0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
270e0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
270f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
27100 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
27110 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
27120 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
27130 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
27140 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
27150 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
27160 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
27170 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
27180 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
27190 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
271a0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
271b0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
271c0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
271d0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
271e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
271f0 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
27200 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
27210 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
27220 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
27230 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
27240 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
27250 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
27260 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
27270 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
27280 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
27290 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
272a0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
272b0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
272c0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
272d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
272e0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
272f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27300 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
27310 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
27320 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
27330 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
27340 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
27350 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
27360 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27370 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
27380 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
27390 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
273a0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
273b0 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
273c0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
273d0 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
273e0 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
273f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27400 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
27410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27420 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
27430 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
27440 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
27450 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
27460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
27470 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
27480 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
27490 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
274a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
274b0 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
274c0 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
274d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
274e0 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
274f0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
27500 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
27510 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
27520 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
27530 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
27540 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
27550 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
27560 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
27570 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
27580 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
27590 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
275a0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
275b0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
275c0 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
275d0 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
275e0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
275f0 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
27600 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
27610 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
27620 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
27630 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
27640 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
27650 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
27660 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
27670 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
27680 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
27690 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
276a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
276b0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
276c0 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
276d0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
276e0 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
276f0 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
27700 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
27710 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
27720 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
27730 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
27740 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
27750 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
27760 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
27770 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
27780 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
27790 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
277a0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
277b0 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
277c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
277d0 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
277e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
277f0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
27800 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
27810 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27820 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
27830 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
27840 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
27850 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
27860 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
27870 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
27880 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
27890 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
278a0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
278b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
278c0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
278d0 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
278e0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
278f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
27900 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
27910 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
27920 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
27930 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
27940 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
27950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27960 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
27970 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
27980 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
27990 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
279a0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
279b0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
279c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
279d0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
279e0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
279f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27a00 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
27a10 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
27a20 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
27a30 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27a40 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
27a50 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
27a60 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
27a70 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
27a80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
27a90 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
27aa0 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
27ab0 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
27ac0 20 6f 72 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65   or.** or if the
27ad0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
27ae0 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
27af0 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
27b00 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
27b10 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
27b20 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
27b30 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
27b40 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
27b50 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
27b60 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
27b70 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
27b80 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
27b90 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
27ba0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
27bb0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
27bc0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
27bd0 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
27be0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
27bf0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
27c00 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
27c10 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
27c20 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
27c30 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
27c40 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
27c50 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
27c60 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
27c70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
27c80 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
27c90 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
27ca0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27cb0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
27cc0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
27cd0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
27ce0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
27cf0 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
27d00 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
27d10 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
27d20 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
27d30 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
27d40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
27d50 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
27d60 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
27d70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27d80 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
27d90 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
27da0 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
27db0 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
27dc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27dd0 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
27de0 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
27df0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
27e00 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
27e10 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
27e20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
27e30 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
27e40 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
27e50 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
27e60 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
27e70 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
27e80 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
27e90 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
27ea0 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
27eb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
27ec0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
27ed0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
27ee0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
27ef0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
27f00 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
27f10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27f20 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
27f30 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
27f40 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
27f50 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
27f60 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
27f70 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
27f80 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
27f90 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
27fa0 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
27fb0 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
27fc0 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
27fd0 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
27fe0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
27ff0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
28000 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
28010 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
28020 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
28030 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
28040 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
28050 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
28060 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
28070 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
28080 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
28090 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
280a0 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
280b0 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
280c0 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
280d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
280e0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
280f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
28100 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
28110 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28120 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
28130 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
28140 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
28150 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
28160 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
28170 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
28180 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
28190 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
281a0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
281b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
281c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
281d0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
281e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
281f0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
28200 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28210 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
28220 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
28230 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
28240 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
28250 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
28260 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
28270 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
28280 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
28290 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
282a0 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
282b0 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
282c0 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
282d0 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
282e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
282f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28300 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
28310 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
28320 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
28330 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
28340 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
28350 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
28360 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
28370 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
28380 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
28390 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
283a0 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
283b0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
283c0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
283d0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
283e0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
283f0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
28400 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
28410 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
28420 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
28430 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
28440 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
28450 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
28460 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
28470 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
28480 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
28490 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
284a0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
284b0 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
284c0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
284d0 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
284e0 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
284f0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
28500 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
28510 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
28520 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
28530 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
28540 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
28550 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
28560 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
28570 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
28580 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
28590 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
285a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
285b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
285c0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
285d0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
285e0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
285f0 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
28600 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
28610 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
28620 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
28630 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
28640 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28650 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
28660 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
28670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
28680 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
28690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
286a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
286b0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
286c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
286d0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
286e0 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
286f0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
28700 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
28710 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
28720 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
28730 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
28740 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
28750 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
28760 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
28770 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
28780 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
28790 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
287a0 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
287b0 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
287c0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
287d0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
287e0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
287f0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
28800 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
28810 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
28820 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
28830 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
28840 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
28850 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
28860 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
28870 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
28880 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
28890 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
288a0 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
288b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
288c0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
288d0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
288e0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
288f0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
28900 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
28910 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
28920 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
28930 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
28940 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
28950 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
28960 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
28970 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
28980 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
28990 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
289a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
289b0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
289c0 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
289d0 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
289e0 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
289f0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
28a00 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
28a10 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
28a20 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
28a30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
28a40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
28a50 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
28a60 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
28a70 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
28a80 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
28a90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
28aa0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
28ab0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
28ac0 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
28ad0 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
28ae0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
28af0 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
28b00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28b10 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
28b20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
28b30 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
28b40 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
28b50 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
28b60 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
28b70 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
28b80 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
28b90 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
28ba0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
28bb0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
28bc0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
28bd0 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
28be0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
28bf0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
28c00 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
28c10 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
28c20 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
28c30 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
28c40 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
28c50 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
28c60 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
28c70 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
28c80 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
28c90 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
28ca0 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
28cb0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
28cc0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
28cd0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
28ce0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28cf0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
28d00 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
28d10 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
28d20 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
28d30 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
28d40 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
28d50 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
28d60 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
28d70 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
28d80 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
28d90 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
28da0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
28db0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
28dc0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
28dd0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
28de0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
28df0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
28e00 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
28e10 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
28e20 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
28e30 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
28e40 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
28e50 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
28e60 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
28e70 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
28e80 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
28e90 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
28ea0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28eb0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
28ec0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
28ed0 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
28ee0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
28ef0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
28f00 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
28f10 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
28f20 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
28f30 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
28f40 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
28f50 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
28f60 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
28f70 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
28f80 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
28f90 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
28fa0 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
28fb0 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
28fc0 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
28fd0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
28fe0 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
28ff0 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
29000 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
29010 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
29020 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
29030 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
29040 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
29050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
29060 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
29070 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
29080 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
29090 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
290a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
290b0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
290c0 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
290d0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
290e0 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
290f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
29100 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
29110 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
29120 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
29130 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
29140 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
29150 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
29160 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
29170 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29180 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29190 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
291a0 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
291b0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
291c0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
291d0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
291e0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
291f0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
29200 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
29210 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
29220 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
29230 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
29240 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
29250 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
29260 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
29270 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
29280 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
29290 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
292a0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
292b0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
292c0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
292d0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
292e0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
292f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
29300 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
29310 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
29320 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
29330 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
29340 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
29350 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
29360 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
29370 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
29380 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
29390 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
293a0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
293b0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
293c0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
293d0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
293e0 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
293f0 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
29400 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
29410 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
29420 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
29430 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
29440 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
29450 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
29460 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
29470 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
29480 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
29490 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
294a0 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
294b0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
294c0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
294d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
294e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
294f0 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
29500 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29510 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
29520 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
29530 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
29540 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
29550 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
29560 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
29570 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
29580 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
29590 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
295a0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
295b0 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
295c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
295d0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
295e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
295f0 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
29600 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
29610 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
29620 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
29630 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
29640 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
29650 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
29660 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
29670 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
29680 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
29690 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
296a0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
296b0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
296c0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
296d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
296e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
296f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
29700 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
29710 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
29720 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
29730 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
29740 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
29750 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
29760 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
29770 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
29780 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
29790 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
297a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
297b0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
297c0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
297d0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
297e0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
297f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29800 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
29810 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
29820 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
29830 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
29840 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
29850 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
29860 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
29870 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
29880 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
29890 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
298a0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
298b0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
298c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
298d0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
298e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
298f0 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
29900 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
29910 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29920 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
29930 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
29940 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
29950 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
29960 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
29970 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
29980 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
29990 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
299a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
299b0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
299c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
299d0 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
299e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
299f0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
29a00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
29a10 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
29a20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
29a30 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
29a40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
29a50 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
29a60 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
29a70 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
29a80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
29a90 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
29aa0 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
29ab0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
29ac0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
29ad0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
29ae0 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
29af0 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
29b00 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
29b10 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
29b20 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
29b30 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
29b40 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
29b50 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
29b60 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
29b70 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
29b80 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
29b90 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
29ba0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
29bb0 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
29bc0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
29bd0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
29be0 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
29bf0 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
29c00 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
29c10 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
29c20 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
29c30 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
29c40 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
29c50 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
29c60 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
29c70 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
29c80 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
29c90 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
29ca0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
29cb0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
29cc0 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
29cd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
29ce0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
29cf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
29d00 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
29d10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
29d20 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
29d30 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
29d40 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
29d50 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
29d60 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
29d70 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
29d80 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
29d90 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
29da0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
29db0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
29dc0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
29dd0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
29de0 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
29df0 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
29e00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29e10 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
29e20 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
29e30 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
29e40 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
29e50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
29e60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
29e70 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
29e80 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
29e90 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
29ea0 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
29eb0 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
29ec0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
29ed0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
29ee0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
29ef0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
29f00 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
29f10 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
29f20 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
29f30 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
29f40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
29f50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
29f60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
29f70 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
29f80 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
29f90 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
29fa0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
29fb0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
29fc0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
29fd0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
29fe0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
29ff0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
2a000 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a010 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2a020 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
2a030 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2a040 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
2a050 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
2a060 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2a070 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
2a080 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
2a090 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
2a0a0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
2a0b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2a0c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2a0d0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
2a0e0 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
2a0f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2a100 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
2a110 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
2a120 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2a130 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
2a140 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
2a150 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
2a160 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
2a170 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
2a180 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2a190 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
2a1a0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2a1b0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2a1c0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
2a1d0 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
2a1e0 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
2a1f0 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
2a200 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2a210 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
2a220 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
2a230 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
2a240 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
2a250 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
2a260 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
2a270 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2a280 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
2a290 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
2a2a0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
2a2b0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2a2c0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
2a2d0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
2a2e0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
2a2f0 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
2a300 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
2a310 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
2a320 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
2a330 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
2a340 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
2a350 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
2a360 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2a370 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
2a380 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2a390 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
2a3a0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
2a3b0 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
2a3c0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
2a3d0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
2a3e0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
2a3f0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
2a400 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2a410 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
2a420 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
2a430 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
2a440 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
2a450 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
2a460 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
2a470 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
2a480 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
2a490 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
2a4a0 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
2a4b0 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
2a4c0 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
2a4d0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
2a4e0 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
2a4f0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
2a500 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
2a510 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2a520 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
2a530 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
2a540 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
2a550 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
2a560 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
2a570 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
2a580 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
2a590 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2a5a0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
2a5b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2a5c0 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
2a5d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2a5e0 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
2a5f0 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
2a600 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
2a610 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2a620 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
2a630 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2a640 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
2a650 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
2a660 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
2a670 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
2a680 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2a690 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
2a6a0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2a6b0 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
2a6c0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2a6d0 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
2a6e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2a6f0 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
2a700 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
2a710 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2a720 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2a730 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2a740 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
2a750 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2a760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2a770 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
2a780 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
2a790 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
2a7a0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2a7b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2a7c0 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
2a7d0 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
2a7e0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2a7f0 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
2a800 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2a810 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2a820 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2a830 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
2a840 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2a850 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2a860 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
2a870 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
2a880 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2a890 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
2a8a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2a8b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2a8c0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
2a8d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2a8e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2a8f0 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
2a900 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2a910 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
2a920 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
2a930 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
2a940 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
2a950 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
2a960 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
2a970 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
2a980 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
2a990 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
2a9a0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
2a9b0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
2a9c0 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
2a9d0 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
2a9e0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
2a9f0 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
2aa00 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2aa10 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
2aa20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
2aa30 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
2aa40 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
2aa50 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
2aa60 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
2aa70 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
2aa80 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
2aa90 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
2aaa0 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
2aab0 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
2aac0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
2aad0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2aae0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2aaf0 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
2ab00 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
2ab10 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
2ab20 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
2ab30 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
2ab40 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
2ab50 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
2ab60 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
2ab70 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
2ab80 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
2ab90 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
2aba0 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
2abb0 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
2abc0 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
2abd0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2abe0 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
2abf0 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
2ac00 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
2ac10 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
2ac20 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
2ac30 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
2ac40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2ac50 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
2ac60 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
2ac70 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
2ac80 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
2ac90 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
2aca0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2acb0 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
2acc0 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
2acd0 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
2ace0 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
2acf0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
2ad00 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2ad10 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
2ad20 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
2ad30 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20  LL pointer if N 
2ad40 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
2ad50 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
2ad60 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
2ad70 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
2ad80 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
2ad90 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
2ada0 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
2adb0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2adc0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
2add0 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
2ade0 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
2adf0 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
2ae00 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
2ae10 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
2ae20 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
2ae30 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
2ae40 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2ae50 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
2ae60 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
2ae70 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
2ae80 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
2ae90 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
2aea0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
2aeb0 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  on.)^.**.** ^SQL
2aec0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
2aed0 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
2aee0 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
2aef0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
2af00 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2af10 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
2af20 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
2af30 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
2af40 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
2af50 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
2af60 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2af70 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
2af80 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
2af90 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
2afa0 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
2afb0 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
2afc0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
2afd0 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
2afe0 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
2aff0 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
2b000 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
2b010 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
2b020 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2b030 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2b040 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
2b050 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2b060 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
2b070 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
2b080 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
2b090 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b0a0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
2b0b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
2b0c0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
2b0d0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
2b0e0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
2b0f0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2b100 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2b110 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2b120 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
2b130 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
2b140 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
2b150 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2b160 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2b170 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2b180 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2b190 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2b1a0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2b1b0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2b1c0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2b1d0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2b1e0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2b1f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2b200 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2b210 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2b220 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2b230 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2b240 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2b250 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
2b260 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
2b270 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2b280 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
2b290 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2b2a0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
2b2b0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
2b2c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2b2d0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2b2e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b2f0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2b300 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
2b310 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2b320 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
2b330 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
2b340 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2b350 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2b360 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2b370 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2b380 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2b390 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2b3a0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2b3b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2b3c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2b3d0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
2b3e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2b3f0 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
2b400 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
2b410 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
2b420 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
2b430 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ata.**.** The fo
2b440 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
2b450 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
2b460 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
2b470 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
2b480 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
2b490 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
2b4a0 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
2b4b0 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
2b4c0 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
2b4d0 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
2b4e0 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
2b4f0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
2b500 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
2b510 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
2b520 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
2b530 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
2b540 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
2b550 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
2b560 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
2b570 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
2b580 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
2b590 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
2b5a0 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
2b5b0 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
2b5c0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
2b5d0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2b5e0 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
2b5f0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2b600 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
2b610 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
2b620 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
2b630 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
2b640 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
2b650 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
2b660 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
2b670 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
2b680 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
2b690 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2b6a0 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
2b6b0 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
2b6c0 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
2b6d0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
2b6e0 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
2b6f0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
2b700 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b710 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
2b720 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2b730 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2b740 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
2b750 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
2b760 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2b770 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
2b780 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
2b790 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
2b7a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b7b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2b7c0 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61  n. ^If no metada
2b7d0 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72  ta has been ever
2b7e0 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72  .** been set for
2b7f0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
2b800 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  t of the functio
2b810 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72  n, or if the cor
2b820 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75  responding.** fu
2b830 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
2b840 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e   has changed sin
2b850 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  ce the meta-data
2b860 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65   was set,.** the
2b870 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  n sqlite3_get_au
2b880 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20  xdata() returns 
2b890 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2b8a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b8b0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2b8c0 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
2b8d0 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
2b8e0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
2b8f0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
2b900 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   as the metadata
2b910 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
2b920 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
2b930 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2b940 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
2b950 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
2b960 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
2b970 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
2b980 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
2b990 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
2b9a0 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
2b9b0 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  oyed..** ^If it 
2b9c0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
2b9d0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
2b9e0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
2b9f0 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
2ba00 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
2ba10 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2ba20 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
2ba30 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74  n.** the metadat
2ba40 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
2ba50 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
2ba60 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
2ba70 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
2ba80 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2ba90 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
2baa0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
2bab0 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
2bac0 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
2bad0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
2bae0 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61  nd drop metadata
2baf0 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d   on any.** param
2bb00 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63  eter of any func
2bb10 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65  tion at any time
2bb20 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61  .  ^The only gua
2bb30 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
2bb40 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
2bb50 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
2bb60 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
2bb70 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
2bb80 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
2bb90 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
2bba0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
2bbb0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
2bbc0 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
2bbd0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
2bbe0 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
2bbf0 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
2bc00 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
2bc10 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
2bc20 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a  ameters].)^.**.*
2bc30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2bc40 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2bc50 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2bc60 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2bc70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2bc80 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
2bc90 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
2bca0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
2bcb0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2bcc0 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
2bcd0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
2bce0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2bcf0 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
2bd00 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
2bd10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bd20 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
2bd30 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
2bd40 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
2bd50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
2bd60 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
2bd70 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
2bd80 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
2bd90 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
2bda0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
2bdb0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2bdc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2bdd0 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
2bde0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
2bdf0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
2be00 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
2be10 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
2be20 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
2be30 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
2be40 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
2be50 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
2be60 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
2be70 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
2be80 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
2be90 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
2bea0 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
2beb0 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
2bec0 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
2bed0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
2bee0 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
2bef0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2bf00 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2bf10 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
2bf20 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
2bf30 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
2bf40 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
2bf50 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
2bf60 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
2bf70 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
2bf80 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
2bf90 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
2bfa0 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
2bfb0 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
2bfc0 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
2bfd0 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
2bfe0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
2bff0 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
2c000 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
2c010 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
2c020 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2c030 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
2c040 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
2c050 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
2c060 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a  QL Function.**.*
2c070 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2c080 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
2c090 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
2c0a0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
2c0b0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
2c0c0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2c0d0 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
2c0e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2c0f0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2c100 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2c110 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2c120 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
2c130 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2c140 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2c150 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
2c160 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
2c170 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
2c180 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
2c190 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
2c1a0 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
2c1b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2c1c0 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
2c1d0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
2c1e0 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
2c1f0 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
2c200 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2c210 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2c220 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c230 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2c240 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2c250 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
2c260 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
2c270 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2c280 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
2c290 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
2c2a0 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
2c2b0 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
2c2c0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
2c2d0 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
2c2e0 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
2c2f0 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
2c300 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
2c310 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2c320 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74  t_zeroblob() int
2c330 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
2c340 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
2c350 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2c360 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2c370 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
2c380 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
2c390 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
2c3a0 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
2c3b0 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
2c3c0 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
2c3d0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
2c3e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2c3f0 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
2c400 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2c410 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
2c420 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c430 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2c440 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
2c450 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
2c460 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
2c470 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
2c480 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2c490 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2c4a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2c4b0 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
2c4c0 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
2c4d0 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
2c4e0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
2c4f0 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
2c500 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  ..** ^SQLite use
2c510 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
2c520 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
2c530 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
2c540 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
2c550 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
2c560 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c570 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
2c580 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
2c590 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69   message.  ^SQLi
2c5a0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
2c5b0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
2c5c0 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
2c5d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2c5e0 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
2c5f0 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72  ^SQLite.** inter
2c600 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
2c610 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
2c620 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
2c630 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
2c640 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
2c650 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  .  ^If the third
2c660 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2c670 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2c680 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2c690 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2c6a0 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
2c6b0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
2c6c0 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
2c6d0 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
2c6e0 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
2c6f0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
2c700 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
2c710 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2c720 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
2c730 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a  sult_error() or.
2c740 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2c750 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
2c760 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e  on-negative then
2c770 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
2c780 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73  at many.** bytes
2c790 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
2c7a0 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  ) from the 2nd p
2c7b0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2c7c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
2c7d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2c7e0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2c7f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2c800 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
2c810 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
2c820 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2c830 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2c840 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
2c850 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
2c860 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
2c870 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
2c880 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
2c890 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
2c8a0 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
2c8b0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
2c8c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2c8d0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
2c8e0 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
2c8f0 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
2c900 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2c910 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
2c920 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
2c930 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
2c940 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20  ^By default,.** 
2c950 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
2c960 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
2c970 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63   ^A subsequent c
2c980 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
2c990 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
2c9a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2c9b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
2c9c0 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
2c9d0 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
2c9e0 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OR..**.** ^The s
2c9f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f  qlite3_result_to
2ca00 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
2ca10 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2ca20 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
2ca30 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
2ca40 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
2ca50 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67  BLOB is too long
2ca60 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
2ca70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ca80 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29  3_result_nomem()
2ca90 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2caa0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
2cab0 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
2cac0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
2cad0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2cae0 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
2caf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2cb00 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
2cb10 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2cb20 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2cb30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2cb40 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2cb50 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
2cb60 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2cb70 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2cb80 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2cb90 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ent..** ^The sql
2cba0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
2cbb0 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
2cbc0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
2cbd0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
2cbe0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2cbf0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2cc00 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
2cc10 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
2cc20 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
2cc30 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
2cc40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2cc50 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
2cc60 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2cc70 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2cc80 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2cc90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2cca0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
2ccb0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
2ccc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2ccd0 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
2cce0 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
2ccf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2cd00 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
2cd10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cd20 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
2cd30 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
2cd40 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2cd50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2cd60 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2cd70 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
2cd80 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
2cd90 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
2cda0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
2cdb0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
2cdc0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
2cdd0 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
2cde0 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
2cdf0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2ce00 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
2ce10 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
2ce20 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
2ce30 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
2ce40 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
2ce50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2ce60 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2ce70 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
2ce80 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2ce90 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2cea0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2ceb0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
2cec0 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
2ced0 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
2cee0 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
2cef0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
2cf00 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2cf10 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
2cf20 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
2cf30 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2cf40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cf50 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2cf60 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
2cf70 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
2cf80 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
2cf90 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
2cfa0 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
2cfb0 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
2cfc0 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
2cfd0 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
2cfe0 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
2cff0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a  unction result..
2d000 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
2d010 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2d020 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d030 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2d040 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2d050 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
2d060 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
2d070 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
2d080 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
2d090 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
2d0a0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
2d0b0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
2d0c0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
2d0d0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
2d0e0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
2d0f0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
2d100 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2d110 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2d120 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
2d130 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
2d140 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
2d150 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
2d160 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
2d170 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
2d180 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
2d190 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
2d1a0 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
2d1b0 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
2d1c0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
2d1d0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2d1e0 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
2d1f0 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
2d200 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
2d210 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
2d220 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
2d230 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
2d240 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2d250 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2d260 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2d270 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2d280 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d290 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
2d2a0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
2d2b0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
2d2c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
2d2d0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
2d2e0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
2d2f0 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
2d300 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2d310 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
2d320 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
2d330 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d340 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2d350 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2d360 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
2d370 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2d380 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2d390 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
2d3a0 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
2d3b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d3c0 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
2d3d0 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
2d3e0 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
2d3f0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2d400 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
2d410 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
2d420 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2d430 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
2d440 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
2d450 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
2d460 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2d470 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
2d480 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
2d490 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
2d4a0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
2d4b0 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
2d4c0 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
2d4d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d4e0 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
2d4f0 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
2d500 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
2d510 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d520 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
2d530 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
2d540 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
2d550 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d560 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
2d570 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
2d580 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
2d590 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2d5a0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
2d5b0 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
2d5c0 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
2d5d0 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
2d5e0 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
2d5f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2d600 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
2d610 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
2d620 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
2d630 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
2d640 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2d650 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2d660 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
2d670 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d680 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2d690 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2d6a0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d6b0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
2d6c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d6d0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
2d6e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2d6f0 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
2d700 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2d710 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2d720 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2d730 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
2d740 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2d750 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2d760 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2d770 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
2d780 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2d790 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d7a0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
2d7b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2d7c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d7d0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
2d7e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d7f0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2d800 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
2d810 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d820 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2d830 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2d840 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d850 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
2d860 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d870 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
2d880 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2d890 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d8a0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
2d8b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2d8c0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
2d8d0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2d8e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d8f0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2d900 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2d910 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2d920 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2d930 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d940 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
2d950 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2d960 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2d970 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2d980 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d990 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
2d9a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2d9b0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
2d9c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2d9d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d9e0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
2d9f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
2da00 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
2da10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2da20 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
2da30 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
2da40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2da50 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
2da60 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
2da70 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
2da80 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
2da90 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
2daa0 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
2dab0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
2dac0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2dad0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
2dae0 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
2daf0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
2db00 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2db10 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
2db20 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
2db30 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
2db40 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2db50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
2db60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2db70 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
2db80 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
2db90 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2dba0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2dbb0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
2dbc0 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
2dbd0 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
2dbe0 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
2dbf0 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
2dc00 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
2dc10 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
2dc20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
2dc30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
2dc40 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
2dc50 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
2dc60 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
2dc70 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
2dc80 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
2dc90 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
2dca0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
2dcb0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
2dcc0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
2dcd0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
2dce0 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
2dcf0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2dd00 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
2dd10 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
2dd20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
2dd30 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
2dd40 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
2dd50 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
2dd60 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2dd70 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
2dd80 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
2dd90 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
2dda0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
2ddb0 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
2ddc0 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
2ddd0 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
2dde0 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
2ddf0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
2de00 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
2de10 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
2de20 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
2de30 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
2de40 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
2de50 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
2de60 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
2de70 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2de80 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
2de90 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2dea0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
2deb0 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
2dec0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
2ded0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
2dee0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2def0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
2df00 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2df10 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
2df20 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
2df30 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
2df40 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
2df50 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
2df60 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
2df70 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
2df80 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
2df90 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
2dfa0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
2dfb0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
2dfc0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
2dfd0 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
2dfe0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
2dff0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2e000 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
2e010 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
2e020 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
2e030 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
2e040 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
2e050 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
2e060 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
2e070 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
2e080 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
2e090 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
2e0a0 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
2e0b0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
2e0c0 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
2e0d0 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
2e0e0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
2e0f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2e100 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
2e110 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
2e120 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2e130 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
2e140 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
2e150 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
2e160 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
2e170 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
2e180 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
2e190 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
2e1a0 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
2e1b0 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
2e1c0 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
2e1d0 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
2e1e0 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
2e1f0 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
2e200 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
2e210 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
2e220 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
2e230 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
2e240 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
2e250 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
2e260 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
2e270 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
2e280 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
2e290 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
2e2a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
2e2b0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
2e2c0 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
2e2d0 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
2e2e0 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
2e2f0 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
2e300 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
2e310 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
2e320 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
2e330 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
2e340 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
2e350 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2e360 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
2e370 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
2e380 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
2e390 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
2e3a0 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
2e3b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
2e3c0 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
2e3d0 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
2e3e0 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
2e3f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
2e400 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
2e410 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
2e420 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
2e430 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
2e440 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
2e450 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2e460 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
2e470 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
2e480 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
2e490 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2e4a0 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
2e4b0 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
2e4c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
2e4d0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
2e4e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2e4f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
2e500 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2e510 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
2e520 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2e530 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
2e540 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
2e550 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
2e560 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
2e570 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
2e580 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
2e590 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
2e5a0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
2e5b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
2e5c0 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
2e5d0 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
2e5e0 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
2e5f0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
2e600 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
2e610 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
2e620 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
2e630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2e640 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
2e650 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2e660 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
2e670 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
2e680 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
2e690 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
2e6a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e6b0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
2e6c0 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
2e6d0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
2e6e0 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
2e6f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2e700 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
2e710 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
2e720 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2e730 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
2e740 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
2e750 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
2e760 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2e770 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
2e780 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
2e790 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
2e7a0 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
2e7b0 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
2e7c0 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
2e7d0 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
2e7e0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
2e7f0 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
2e800 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
2e810 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
2e820 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
2e830 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
2e840 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
2e850 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
2e860 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
2e870 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2e880 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
2e890 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
2e8a0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
2e8b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2e8c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2e8d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2e8e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2e8f0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2e900 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
2e910 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
2e920 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2e930 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2e940 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
2e950 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2e960 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
2e970 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2e980 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2e990 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
2e9a0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
2e9b0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2e9c0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2e9d0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2e9e0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
2e9f0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2ea00 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2ea10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2ea20 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
2ea30 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
2ea40 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
2ea50 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
2ea60 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
2ea70 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2ea80 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2ea90 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
2eaa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2eab0 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
2eac0 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
2ead0 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
2eae0 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
2eaf0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
2eb00 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
2eb10 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
2eb20 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
2eb30 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
2eb40 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
2eb50 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
2eb60 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2eb70 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
2eb80 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2eb90 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
2eba0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
2ebb0 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
2ebc0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
2ebd0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
2ebe0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
2ebf0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2ec00 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
2ec10 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
2ec20 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
2ec30 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
2ec40 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2ec50 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
2ec60 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
2ec70 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
2ec80 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2ec90 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
2eca0 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
2ecb0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
2ecc0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
2ecd0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
2ece0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
2ecf0 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
2ed00 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
2ed10 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
2ed20 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
2ed30 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
2ed40 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
2ed50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2ed60 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
2ed70 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
2ed80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
2ed90 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2eda0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
2edb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2edc0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
2edd0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2ede0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
2edf0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2ee00 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
2ee10 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
2ee20 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2ee30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2ee40 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2ee50 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
2ee60 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
2ee70 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
2ee80 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
2ee90 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
2eea0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
2eeb0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2eec0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2eed0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
2eee0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
2eef0 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
2ef00 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
2ef10 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
2ef20 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
2ef30 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
2ef40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
2ef50 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
2ef60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ef70 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
2ef80 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2ef90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2efa0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
2efb0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2efc0 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
2efd0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
2efe0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2eff0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2f000 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
2f010 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2f020 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2f030 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
2f040 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
2f050 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2f060 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
2f070 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
2f080 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
2f090 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
2f0a0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
2f0b0 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
2f0c0 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
2f0d0 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
2f0e0 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
2f0f0 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
2f100 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
2f110 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2f120 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2f130 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2f140 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2f150 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2f160 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2f170 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
2f180 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2f190 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2f1a0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2f1b0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2f1c0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2f1d0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
2f1e0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
2f1f0 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
2f200 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2f210 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
2f220 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
2f230 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
2f240 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
2f250 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
2f260 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
2f270 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
2f280 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
2f290 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
2f2a0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
2f2b0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
2f2c0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
2f2d0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
2f2e0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
2f2f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2f300 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2f310 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2f320 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2f330 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2f340 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2f350 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2f360 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
2f370 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2f380 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
2f390 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
2f3a0 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
2f3b0 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
2f3c0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
2f3d0 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
2f3e0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
2f3f0 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
2f400 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
2f410 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
2f420 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
2f430 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
2f440 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
2f450 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
2f460 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
2f470 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
2f480 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
2f490 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
2f4a0 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
2f4b0 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
2f4c0 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
2f4d0 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
2f4e0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
2f4f0 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
2f500 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
2f510 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
2f520 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
2f530 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
2f540 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2f550 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
2f560 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
2f570 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f580 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
2f590 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
2f5a0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
2f5b0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
2f5c0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
2f5d0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
2f5e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
2f5f0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
2f600 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
2f610 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
2f620 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
2f630 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
2f640 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
2f650 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
2f660 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
2f670 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
2f680 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
2f690 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
2f6a0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
2f6b0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2f6c0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
2f6d0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
2f6e0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
2f6f0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
2f700 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
2f710 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
2f720 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2f730 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
2f740 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
2f750 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
2f760 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
2f770 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
2f780 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
2f790 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
2f7a0 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
2f7b0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
2f7c0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
2f7d0 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
2f7e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2f7f0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
2f800 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
2f810 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
2f820 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
2f830 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
2f840 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  aphs..*/.int sql
2f850 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
2f860 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f870 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
2f880 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
2f890 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
2f8a0 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
2f8b0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
2f8c0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2f8d0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
2f8e0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
2f8f0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
2f900 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
2f910 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
2f920 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
2f930 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
2f940 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
2f950 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
2f960 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
2f970 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
2f980 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
2f990 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
2f9a0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
2f9b0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2f9c0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
2f9d0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
2f9e0 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
2f9f0 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
2fa00 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
2fa10 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
2fa20 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
2fa30 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
2fa40 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
2fa50 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
2fa60 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
2fa70 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
2fa80 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
2fa90 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
2faa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
2fab0 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
2fac0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
2fad0 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
2fae0 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
2faf0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
2fb00 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
2fb10 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
2fb20 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
2fb30 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
2fb40 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
2fb50 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
2fb60 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
2fb70 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
2fb80 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2fb90 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
2fba0 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
2fbb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
2fbc0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2fbd0 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
2fbe0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2fbf0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
2fc00 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
2fc10 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2fc20 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2fc30 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
2fc40 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
2fc50 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2fc60 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
2fc70 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
2fc80 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
2fc90 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
2fca0 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
2fcb0 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
2fcc0 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
2fcd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
2fce0 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
2fcf0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
2fd00 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
2fd10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
2fd20 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
2fd30 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
2fd40 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
2fd50 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
2fd60 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
2fd70 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
2fd80 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2fd90 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2fda0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2fdb0 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
2fdc0 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
2fdd0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2fde0 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
2fdf0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
2fe00 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
2fe10 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  r *sqlite3_temp_
2fe20 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
2fe30 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
2fe40 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
2fe50 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44   Mode.** KEYWORD
2fe60 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
2fe70 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ode}.**.** ^The 
2fe80 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
2fe90 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
2fea0 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
2feb0 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
2fec0 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
2fed0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2fee0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
2fef0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
2ff00 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2ff10 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .  ^Autocommit m
2ff20 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
2ff30 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ault..** ^Autoco
2ff40 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
2ff50 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
2ff60 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
2ff70 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
2ff80 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
2ff90 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
2ffa0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
2ffb0 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
2ffc0 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
2ffd0 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
2ffe0 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
2fff0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
30000 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
30010 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
30020 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
30030 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
30040 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
30050 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
30060 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
30070 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
30080 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
30090 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
300a0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
300b0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
300c0 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
300d0 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
300e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
300f0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
30100 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
30110 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
30120 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
30130 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
30140 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
30150 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
30160 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
30170 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
30180 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
30190 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
301a0 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
301b0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
301c0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
301d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
301e0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
301f0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
30200 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
30210 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
30220 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
30230 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
30240 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
30250 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
30260 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
30270 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30280 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
30290 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
302a0 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
302b0 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
302c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
302d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
302e0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
302f0 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
30300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30310 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
30320 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
30330 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
30340 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
30350 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
30360 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
30370 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
30380 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
30390 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
303a0 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
303b0 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
303c0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
303d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
303e0 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
303f0 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
30400 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
30410 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
30420 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
30430 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
30440 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30450 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
30460 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
30470 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
30480 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
30490 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
304a0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
304b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
304c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
304d0 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
304e0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
304f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
30500 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30510 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
30520 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
30530 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
30540 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
30550 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
30560 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
30570 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
30580 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30590 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
305a0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
305b0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
305c0 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
305d0 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
305e0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
305f0 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
30600 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
30610 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
30620 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
30630 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
30640 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
30650 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
30660 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
30670 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
30680 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
30690 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
306a0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
306b0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
306c0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
306d0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
306e0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
306f0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
30700 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
30710 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
30720 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
30730 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
30740 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
30750 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
30760 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
30770 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
30780 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30790 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
307a0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
307b0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
307c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
307d0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
307e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
307f0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
30800 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
30810 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
30820 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
30830 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
30840 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
30850 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
30860 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
30870 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
30880 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
30890 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
308a0 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
308b0 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
308c0 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
308d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
308e0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
308f0 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
30900 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
30910 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
30920 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
30930 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
30940 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
30950 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30960 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
30970 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
30980 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
30990 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
309a0 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
309b0 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
309c0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
309d0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
309e0 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
309f0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
30a00 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
30a10 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
30a20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
30a30 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
30a40 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  D..**.** The cal
30a50 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61  lback implementa
30a60 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
30a70 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
30a80 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
30a90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
30aa0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
30ab0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  ed the callback.
30ac0 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
30ad0 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
30ae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30af0 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
30b00 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
30b10 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
30b20 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
30b30 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
30b40 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
30b50 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72  e commit.** or r
30b60 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20  ollback hook in 
30b70 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
30b80 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
30b90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
30ba0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
30bb0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
30bc0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
30bd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30be0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
30bf0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
30c00 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
30c10 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74  h..**.** ^Regist
30c20 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
30c30 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
30c40 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
30c50 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d  ** ^When the com
30c60 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
30c70 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  k routine return
30c80 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d  s zero, the [COM
30c90 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  MIT].** operatio
30ca0 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  n is allowed to 
30cb0 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c  continue normall
30cc0 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d  y.  ^If the comm
30cd0 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72  it hook.** retur
30ce0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
30cf0 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69  n the [COMMIT] i
30d00 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
30d10 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a   a [ROLLBACK]..*
30d20 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
30d30 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  hook is invoked 
30d40 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68  on a rollback th
30d50 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  at results from 
30d60 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b  a commit.** hook
30d70 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a   returning non-z
30d80 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20  ero, just as it 
30d90 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e  would be with an
30da0 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b  y other rollback
30db0 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ..**.** ^For the
30dc0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
30dd0 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
30de0 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
30df0 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c  have been.** rol
30e00 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
30e10 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
30e20 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
30e30 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
30e40 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
30e50 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
30e60 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
30e70 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20  ck to occur..** 
30e80 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61  ^The rollback ca
30e90 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
30ea0 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
30eb0 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
30ec0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30ed0 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
30ee0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
30ef0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
30f00 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
30f10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   the [sqlite3_up
30f20 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74  date_hook()] int
30f30 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20  erface..*/.void 
30f40 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
30f50 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
30f60 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
30f70 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
30f80 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
30f90 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
30fa0 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
30fb0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
30fc0 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
30fd0 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
30fe0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
30ff0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
31000 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
31010 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
31020 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
31030 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
31040 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31050 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
31060 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
31070 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
31080 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
31090 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
310a0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
310b0 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  eted..** ^Any ca
310c0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
310d0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
310e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
310f0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
31100 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31110 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
31120 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
31130 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
31140 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
31150 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
31160 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f  oke when a.** ro
31170 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
31180 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
31190 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  d..** ^The first
311a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
311b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
311c0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
311d0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
311e0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
311f0 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73  ook()..** ^The s
31200 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61  econd callback a
31210 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
31220 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
31230 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
31240 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
31250 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e  E_UPDATE], depen
31260 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
31270 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
31280 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  d the callback.*
31290 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  * to be invoked.
312a0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
312b0 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
312c0 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
312d0 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
312e0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
312f0 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
31300 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
31310 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
31320 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61  ow..** ^The fina
31330 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
31340 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
31350 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
31360 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20  ** ^In the case 
31370 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68  of an update, th
31380 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  is is the [rowid
31390 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  ] after the upda
313a0 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
313b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61  **.** ^(The upda
313c0 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69  te hook is not i
313d0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
313e0 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c  rnal system tabl
313f0 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69  es are.** modifi
31400 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f  ed (i.e. sqlite_
31410 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
31420 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a  e_sequence).)^.*
31430 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72  *.** ^In the cur
31440 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
31450 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20  ion, the update 
31460 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69  hook.** is not i
31470 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c  nvoked when dupl
31480 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65  ication rows are
31490 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65   deleted because
314a0 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f   of an.** [ON CO
314b0 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46  NFLICT | ON CONF
314c0 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c  LICT REPLACE] cl
314d0 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74  ause.  ^Nor is t
314e0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
314f0 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72  * invoked when r
31500 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
31510 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63  using the [trunc
31520 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
31530 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74  ]..** The except
31540 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20  ions defined in 
31550 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d  this paragraph m
31560 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61  ight change in a
31570 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
31580 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
31590 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
315a0 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ook implementati
315b0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
315c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
315d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
315e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
315f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
31600 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
31610 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
31620 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
31630 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31640 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
31650 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
31660 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
31670 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
31680 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
31690 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
316a0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a  he update hook..
316b0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
316c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
316d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
316e0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
316f0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
31700 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31710 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
31720 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
31730 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
31740 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31750 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
31760 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
31770 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
31780 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
31790 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
317a0 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  l.** on the same
317b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
317c0 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
317d0 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
317e0 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a  st call on D..**
317f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
31800 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
31810 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71  _hook()] and [sq
31820 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
31830 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ook()].** interf
31840 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  aces..*/.void *s
31850 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
31860 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ok(.  sqlite3*, 
31870 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  .  void(*)(void 
31880 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73  *,int ,char cons
31890 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  t *,char const *
318a0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c  ,sqlite3_int64),
318b0 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a  .  void*.);../*.
318c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
318d0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
318e0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
318f0 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
31900 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a  shared cache}.**
31910 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
31920 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
31930 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
31940 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
31950 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
31960 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
31970 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b  ctures between [
31980 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31990 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e  ion | connection
319a0 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  s].** to the sam
319b0 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72  e database. Shar
319c0 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ing is enabled i
319d0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
319e0 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69  s true.** and di
319f0 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  sabled if the ar
31a00 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e  gument is false.
31a10 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20  )^.**.** ^Cache 
31a20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  sharing is enabl
31a30 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ed and disabled 
31a40 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72  for an entire pr
31a50 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69  ocess..** This i
31a60 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66  s a change as of
31a70 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
31a80 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20  3.5.0. In prior 
31a90 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
31aa0 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77  te,.** sharing w
31ab0 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
31ac0 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20  sabled for each 
31ad0 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c  thread separatel
31ae0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63  y..**.** ^(The c
31af0 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
31b00 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
31b10 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
31b20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
31b30 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
31b40 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
31b50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
31b60 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
31b70 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
31b80 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
31b90 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
31ba0 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
31bb0 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
31bc0 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
31bd0 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
31be0 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a  were opened.)^.*
31bf0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
31c00 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
31c10 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
31c20 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
31c30 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
31c40 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
31c50 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
31c60 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  ] is returned ot
31c70 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  herwise.)^.**.**
31c80 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20 69   ^Shared cache i
31c90 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
31ca0 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20  fault. But this 
31cb0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
31cc0 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
31cd0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
31ce0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
31cf0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
31d00 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
31d10 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
31d20 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a  t explicitly..**
31d30 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b  .** See Also:  [
31d40 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61  SQLite Shared-Ca
31d50 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74  che Mode].*/.int
31d60 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
31d70 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74  shared_cache(int
31d80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31d90 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46  EF: Attempt To F
31da0 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a  ree Heap Memory.
31db0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31dc0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
31dd0 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  y() interface at
31de0 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e  tempts to free N
31df0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61   bytes.** of hea
31e00 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c  p memory by deal
31e10 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73  locating non-ess
31e20 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ential memory al
31e30 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c  locations.** hel
31e40 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
31e50 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d  e library.   Mem
31e60 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68  ory used to cach
31e70 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61  e database.** pa
31e80 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70  ges to improve p
31e90 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e  erformance is an
31ea0 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d   example of non-
31eb0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
31ec0 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
31ed0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72  lease_memory() r
31ee0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
31ef0 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61  r of bytes actua
31f00 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68  lly freed,.** wh
31f10 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72  ich might be mor
31f20 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74  e or less than t
31f30 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73  he amount reques
31f40 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
31f50 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
31f60 6f 72 79 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ory() routine is
31f70 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69   a no-op returni
31f80 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51  ng zero.** if SQ
31f90 4c 69 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70  Lite is not comp
31fa0 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
31fb0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
31fc0 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a  MANAGEMENT]..*/.
31fd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  int sqlite3_rele
31fe0 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b  ase_memory(int);
31ff0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32000 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74  : Impose A Limit
32010 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a   On Heap Size.**
32020 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32030 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
32040 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
32050 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69  ets and/or queri
32060 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c  es the.** soft l
32070 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75  imit on the amou
32080 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
32090 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
320a0 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
320b0 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74  e..** ^SQLite st
320c0 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65  rives to keep he
320d0 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a  ap memory utiliz
320e0 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20  ation below the 
320f0 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d  soft heap.** lim
32100 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 20 74  it by reducing t
32110 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
32120 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70  es held in the p
32130 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20  age cache.** as 
32140 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67  heap memory usag
32150 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 74 68  es approaches th
32160 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
32170 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32180 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 61 75   is "soft" becau
32190 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53  se even though S
321a0 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
321b0 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74   stay.** below t
321c0 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c  he limit, it wil
321d0 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d  l exceed the lim
321e0 69 74 20 72 61 74 68 65 72 20 74 68 61 6e 20 67  it rather than g
321f0 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53  enerate.** an [S
32200 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72  QLITE_NOMEM] err
32210 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  or.  In other wo
32220 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65  rds, the soft he
32230 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20  ap limit .** is 
32240 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
32250 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
32260 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
32270 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
32280 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 20 73  mit64() is the s
32290 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f  ize of.** the so
322a0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72  ft heap limit pr
322b0 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2c  ior to the call,
322c0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 69 6e 20   or negative in 
322d0 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 0a 2a  the case of an.*
322e0 2a 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  * error.  ^If th
322f0 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20  e argument N is 
32300 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e  negative.** then
32310 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61   no change is ma
32320 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68  de to the soft h
32330 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63  eap limit.  Henc
32340 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  e, the current.*
32350 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f  * size of the so
32360 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
32370 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
32380 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  by invoking.** s
32390 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
323a0 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68 20  _limit64() with 
323b0 61 20 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d  a negative argum
323c0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ent..**.** ^If t
323d0 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73  he argument N is
323e0 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73   zero then the s
323f0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
32400 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
32410 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61  * ^(The soft hea
32420 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65  p limit is not e
32430 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63  nforced in the c
32440 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
32450 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20  ation.** if one 
32460 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f  or more of follo
32470 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20  wing conditions 
32480 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20  are true:.**.** 
32490 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
324a0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
324b0 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e   is set to zero.
324c0 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20  .** <li> Memory 
324d0 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69  accounting is di
324e0 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63  sabled using a c
324f0 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68  ombination of th
32500 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  e.**      [sqlit
32510 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
32520 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
32530 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d  TUS],...) start-
32540 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a  time option and.
32550 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c  **      the [SQL
32560 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
32570 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74  TATUS] compile-t
32580 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
32590 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69  li> An alternati
325a0 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ve page cache im
325b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
325c0 73 70 65 63 69 66 69 65 64 20 75 73 69 6e 67 0a  specified using.
325d0 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
325e0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
325f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c  _CONFIG_PCACHE],
32600 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ...)..** <li> Th
32610 65 20 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c  e page cache all
32620 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20  ocates from its 
32630 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20  own memory pool 
32640 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20  supplied.**     
32650 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   by [sqlite3_con
32660 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
32670 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e  FIG_PAGECACHE],.
32680 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a  ..) rather than.
32690 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65  **      from the
326a0 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29   heap..** </ul>)
326b0 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e  ^.**.** Beginnin
326c0 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
326d0 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65  rsion 3.7.3, the
326e0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
326f0 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20   is enforced.** 
32700 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
32710 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
32720 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
32730 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
32740 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
32750 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76  me option is inv
32760 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51 4c  oked.  With [SQL
32770 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
32780 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a  Y_MANAGEMENT],.*
32790 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  * the soft heap 
327a0 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
327b0 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72  d on every memor
327c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57  y allocation.  W
327d0 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54  ithout.** [SQLIT
327e0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
327f0 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65  MANAGEMENT], the
32800 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32810 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65   is only enforce
32820 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79  d.** when memory
32830 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   is allocated by
32840 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2e   the page cache.
32850 20 20 54 65 73 74 69 6e 67 20 73 75 67 67 65 73    Testing sugges
32860 74 73 20 74 68 61 74 20 62 65 63 61 75 73 65 0a  ts that because.
32870 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61 63 68  ** the page cach
32880 65 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d 69  e is the predomi
32890 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65 72  nate memory user
328a0 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74   in SQLite, most
328b0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
328c0 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61 64   will achieve ad
328d0 65 71 75 61 74 65 20 73 6f 66 74 20 68 65 61 70  equate soft heap
328e0 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65   limit enforceme
328f0 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68  nt without.** th
32900 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54 45  e use of [SQLITE
32910 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
32920 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a  ANAGEMENT]..**.*
32930 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74 61 6e  * The circumstan
32940 63 65 73 20 75 6e 64 65 72 20 77 68 69 63 68 20  ces under which 
32950 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f  SQLite will enfo
32960 72 63 65 20 74 68 65 20 73 6f 66 74 20 68 65 61  rce the soft hea
32970 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63  p limit may.** c
32980 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72 65  hanges in future
32990 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
329a0 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ite..*/.sqlite3_
329b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f  int64 sqlite3_so
329c0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
329d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29  sqlite3_int64 N)
329e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
329f0 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53 6f  F: Deprecated So
32a00 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e  ft Heap Limit In
32a10 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45  terface.** DEPRE
32a20 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73  CATED.**.** This
32a30 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65 64   is a deprecated
32a40 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
32a50 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
32a60 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
32a70 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69   interface.  Thi
32a80 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f  s routine is pro
32a90 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  vided for histor
32aa0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
32ab0 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c  ty.** only.  All
32ac0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
32ad0 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  s should use the
32ae0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  .** [sqlite3_sof
32af0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
32b00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74 68  ] interface rath
32b10 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65  er than this one
32b20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52  ..*/.SQLITE_DEPR
32b30 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
32b40 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
32b50 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a  mit(int N);.../*
32b60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
32b70 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
32b80 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
32b90 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e   A Table.**.** ^
32ba0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
32bb0 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62  urns metadata ab
32bc0 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63  out a specific c
32bd0 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69  olumn of a speci
32be0 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  fic.** database 
32bf0 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65  table accessible
32c00 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61   using the [data
32c10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32c20 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65   handle.** passe
32c30 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
32c40 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
32c50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
32c60 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
32c70 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
32c80 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
32c90 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a  h parameters to.
32ca0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
32cb0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
32cc0 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65  rameter is eithe
32cd0 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  r the name of th
32ce0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69  e database.** (i
32cf0 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  .e. "main", "tem
32d00 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68  p", or an attach
32d10 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
32d20 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
32d30 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
32d40 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69  r NULL. ^If it i
32d50 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
32d60 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
32d70 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
32d80 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
32d90 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
32da0 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20   algorithm used 
32db0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
32dc0 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  engine to.** res
32dd0 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
32de0 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
32df0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  s..**.** ^The th
32e00 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
32e10 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
32e20 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
32e30 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
32e40 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
32e50 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
32e60 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
32e70 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
32e80 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
32e90 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
32ea0 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20  ** ^Metadata is 
32eb0 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
32ec0 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
32ed0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
32ee0 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a  ed as the 5th.**
32ef0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
32f00 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
32f10 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e  is function. ^An
32f20 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d  y of these argum
32f30 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e  ents may be.** N
32f40 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
32f50 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
32f60 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
32f70 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74  metadata is omit
32f80 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c  ted..**.** ^(<bl
32f90 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
32fa0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
32fb0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61  ** <tr><th> Para
32fc0 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75  meter <th> Outpu
32fd0 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  t<br>Type <th>  
32fe0 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a  Description.**.*
32ff0 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c  * <tr><td> 5th <
33000 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
33010 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a  <td> Data type.*
33020 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c  * <tr><td> 6th <
33030 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
33040 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66  <td> Name of def
33050 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
33060 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c  equence.** <tr><
33070 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74  td> 7th <td> int
33080 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
33090 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73  ue if column has
330a0 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
330b0 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74  traint.** <tr><t
330c0 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 8th <td> int 
330d0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
330e0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70  e if column is p
330f0 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
33100 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74  RY KEY.** <tr><t
33110 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 9th <td> int 
33120 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
33130 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b  e if column is [
33140 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a  AUTOINCREMENT].*
33150 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
33160 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
33170 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
33180 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
33190 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
331a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
331b0 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61  r the.** declara
331c0 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
331d0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
331e0 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
331f0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a  ntil the next.**
33200 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c   call to any SQL
33210 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
33220 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
33230 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
33240 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
33250 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ew, an [error co
33260 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
33270 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
33280 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
33290 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
332a0 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
332b0 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45  nd an.** [INTEGE
332c0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
332d0 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
332e0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
332f0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
33300 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
33310 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
33320 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
33330 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28  lared column. ^(
33340 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a  If there is no.*
33350 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  * explicitly dec
33360 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50  lared [INTEGER P
33370 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
33380 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  mn, then the out
33390 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
333a0 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c  s are set as fol
333b0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  lows:.**.** <pre
333c0 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79  >.**     data ty
333d0 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a  pe: "INTEGER".**
333e0 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73       collation s
333f0 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59  equence: "BINARY
33400 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c  ".**     not nul
33410 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d  l: 0.**     prim
33420 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20  ary key: 1.**   
33430 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74    auto increment
33440 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  : 0.** </pre>)^.
33450 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
33460 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
33470 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
33480 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
33490 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
334a0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
334b0 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
334c0 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
334d0 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
334e0 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
334f0 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65   be found, an [e
33500 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
33510 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
33520 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74  ror message left
33530 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61  .** in the [data
33540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33550 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
33560 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
33570 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a  errmsg()).)^.**.
33580 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20  ** ^This API is 
33590 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
335a0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
335b0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
335c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
335d0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
335e0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
335f0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
33600 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
33610 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
33620 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
33630 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
33640 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
33650 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
33660 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
33670 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
33680 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
33690 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
336a0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
336b0 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
336c0 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
336d0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
336e0 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
336f0 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
33700 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
33710 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
33720 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
33730 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
33740 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
33750 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
33760 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
33770 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
33780 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
33790 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
337a0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
337b0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
337c0 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
337d0 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
337e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
337f0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
33800 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
33810 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
33820 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
33830 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
33840 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75   if column is au
33850 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
33860 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33870 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
33880 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  nsion.**.** ^Thi
33890 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64  s interface load
338a0 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  s an SQLite exte
338b0 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72  nsion library fr
338c0 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c  om the named fil
338d0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e..**.** ^The sq
338e0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
338f0 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
33900 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61   attempts to loa
33910 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65  d an.** SQLite e
33920 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
33930 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
33940 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a  e file zFile..**
33950 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70  .** ^The entry p
33960 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a  oint is zProc..*
33970 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20  * ^zProc may be 
33980 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  0, in which case
33990 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
339a0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
339b0 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c  defaults to "sql
339c0 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
339d0 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nit"..** ^The sq
339e0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
339f0 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
33a00 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
33a10 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
33a20 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45  ss and [SQLITE_E
33a30 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69  RROR] if somethi
33a40 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
33a50 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  * ^If an error o
33a60 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
33a70 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
33a80 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  n the.** [sqlite
33a90 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
33aa0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  ()] interface sh
33ab0 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a  all attempt to.*
33ac0 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67  * fill *pzErrMsg
33ad0 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73   with error mess
33ae0 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20  age text stored 
33af0 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74  in memory.** obt
33b00 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
33b10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54  te3_malloc()]. T
33b20 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
33b30 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72  ion.** should fr
33b40 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62  ee this memory b
33b50 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
33b60 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
33b70 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
33b80 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61  ding must be ena
33b90 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  bled using.** [s
33ba0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
33bb0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
33bc0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
33bd0 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74   this API,.** ot
33be0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
33bf0 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
33c00 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
33c10 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  o the [load_exte
33c20 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63  nsion() SQL func
33c30 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  tion]..*/.int sq
33c40 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
33c50 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  sion(.  sqlite3 
33c60 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
33c70 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73   Load the extens
33c80 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61  ion into this da
33c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33ca0 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
33cb0 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20  r *zFile,    /* 
33cc0 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72  Name of the shar
33cd0 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  ed library conta
33ce0 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20  ining extension 
33cf0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
33d00 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e  *zProc,    /* En
33d10 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69  try point.  Deri
33d20 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69  ved from zFile i
33d30 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  f 0 */.  char **
33d40 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f  pzErrMsg       /
33d50 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73  * Put error mess
33d60 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20  age here if not 
33d70 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  0 */.);../*.** C
33d80 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
33d90 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
33da0 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
33db0 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f  ** ^So as not to
33dc0 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68   open security h
33dd0 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70  oles in older ap
33de0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
33df0 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65  are.** unprepare
33e00 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65  d to deal with e
33e10 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
33e20 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73  , and as a means
33e30 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a   of disabling.**
33e40 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
33e50 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74  ng while evaluat
33e60 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64  ing user-entered
33e70 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77   SQL, the follow
33e80 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72  ing API.** is pr
33e90 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74  ovided to turn t
33ea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
33eb0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65  _extension()] me
33ec0 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f  chanism on and o
33ed0 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  ff..**.** ^Exten
33ee0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20  sion loading is 
33ef0 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20  off by default. 
33f00 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33  See ticket #1863
33f10 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73  ..** ^Call the s
33f20 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
33f30 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72  ad_extension() r
33f40 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66  outine with onof
33f50 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20  f==1.** to turn 
33f60 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
33f70 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74  g on and call it
33f80 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74   with onoff==0 t
33f90 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63  o turn.** it bac
33fa0 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a  k off again..*/.
33fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
33fc0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
33fd0 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69  n(sqlite3 *db, i
33fe0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
33ff0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f  * CAPI3REF: Auto
34000 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 53  matically Load S
34010 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65 64  tatically Linked
34020 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a   Extensions.**.*
34030 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
34040 65 20 63 61 75 73 65 73 20 74 68 65 20 78 45 6e  e causes the xEn
34050 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63 74  tryPoint() funct
34060 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
34070 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e 65  d for.** each ne
34080 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
34090 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73 20  ection] that is 
340a0 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 64  created.  The id
340b0 65 61 20 68 65 72 65 20 69 73 20 74 68 61 74 0a  ea here is that.
340c0 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  ** xEntryPoint()
340d0 20 69 73 20 74 68 65 20 65 6e 74 72 79 20 70 6f   is the entry po
340e0 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69 63  int for a static
340f0 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c 69  ally linked SQLi
34100 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20  te extension.** 
34110 74 68 61 74 20 69 73 20 74 6f 20 62 65 20 61 75  that is to be au
34120 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61 64  tomatically load
34130 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77 20  ed into all new 
34140 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34150 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  ions..**.** ^(Ev
34160 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66 75  en though the fu
34170 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70 65  nction prototype
34180 20 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e 74   shows that xEnt
34190 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73 0a  ryPoint() takes.
341a0 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  ** no arguments 
341b0 61 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69 64  and returns void
341c0 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  , SQLite invokes
341d0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77   xEntryPoint() w
341e0 69 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72 67  ith three.** arg
341f0 75 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65 63  uments and expec
34200 74 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20 72  ts and integer r
34210 65 73 75 6c 74 20 61 73 20 69 66 20 74 68 65 20  esult as if the 
34220 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65  signature of the
34230 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  .** entry point 
34240 77 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  where as follows
34250 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
34260 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62  ote><pre>.** &nb
34270 73 70 3b 20 20 69 6e 74 20 78 45 6e 74 72 79 50  sp;  int xEntryP
34280 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b 20  oint(.** &nbsp; 
34290 20 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a     sqlite3 *db,.
342a0 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e  ** &nbsp;    con
342b0 73 74 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  st char **pzErrM
342c0 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  sg,.** &nbsp;   
342d0 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
342e0 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
342f0 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e  es *pThunk.** &n
34300 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72  bsp;  );.** </pr
34310 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
34320 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78  ^.**.** If the x
34330 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75 74 69  EntryPoint routi
34340 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e  ne encounters an
34350 20 65 72 72 6f 72 2c 20 69 74 20 73 68 6f 75 6c   error, it shoul
34360 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73 67  d make *pzErrMsg
34370 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
34380 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
34390 72 20 6d 65 73 73 61 67 65 20 28 6f 62 74 61 69  r message (obtai
343a0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
343b0 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a 2a  3_mprintf()]).**
343c0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 61   and return an a
343d0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
343e0 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69 74  r code].  ^SQLit
343f0 65 20 65 6e 73 75 72 65 73 20 74 68 61 74 20 2a  e ensures that *
34400 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20 4e  pzErrMsg.** is N
34410 55 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c 69  ULL before calli
34420 6e 67 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69  ng the xEntryPoi
34430 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74 65 20 77  nt().  ^SQLite w
34440 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73  ill invoke.** [s
34450 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
34460 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61 66 74 65  n *pzErrMsg afte
34470 72 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  r xEntryPoint() 
34480 72 65 74 75 72 6e 73 2e 20 20 5e 49 66 20 61 6e  returns.  ^If an
34490 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74  y.** xEntryPoint
344a0 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  () returns an er
344b0 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ror, the [sqlite
344c0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
344d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
344e0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
344f0 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74 68  en_v2()] call th
34500 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20  at provoked the 
34510 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69  xEntryPoint() wi
34520 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ll fail..**.** ^
34530 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
34540 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 58  auto_extension(X
34550 29 20 77 69 74 68 20 61 6e 20 65 6e 74 72 79 20  ) with an entry 
34560 70 6f 69 6e 74 20 58 20 74 68 61 74 20 69 73 20  point X that is 
34570 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74 68  already.** on th
34580 65 20 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d 61  e list of automa
34590 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
345a0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
345b0 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70 6f  op. ^No entry po
345c0 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 63  int.** will be c
345d0 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e 20  alled more than 
345e0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 64 61  once for each da
345f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34600 6e 20 74 68 61 74 20 69 73 20 6f 70 65 6e 65 64  n that is opened
34610 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34620 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  : [sqlite3_reset
34630 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
34640 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
34650 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
34660 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
34670 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
34680 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
34690 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
346a0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
346b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
346c0 65 72 66 61 63 65 20 64 69 73 61 62 6c 65 73 20  erface disables 
346d0 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65 78  all automatic ex
346e0 74 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f 75  tensions previou
346f0 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  sly.** registere
34700 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
34710 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
34720 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  )]..*/.void sqli
34730 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
34740 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  xtension(void);.
34750 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
34760 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
34770 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
34780 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ism is currently
34790 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
347a0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
347b0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
347c0 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
347d0 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
347e0 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
347f0 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
34800 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
34810 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
34820 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
34830 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
34840 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
34850 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20  ism stabilizes, 
34860 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
34870 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
34880 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
34890 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
348a0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
348b0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a   comment..*/../*
348c0 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75  .** Structures u
348d0 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75  sed by the virtu
348e0 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
348f0 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ce.*/.typedef st
34900 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
34910 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a  b sqlite3_vtab;.
34920 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
34930 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
34940 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  o sqlite3_index_
34950 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74  info;.typedef st
34960 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
34970 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33  b_cursor sqlite3
34980 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79  _vtab_cursor;.ty
34990 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
349a0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69  ite3_module sqli
349b0 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a  te3_module;../*.
349c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
349d0 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63  tual Table Objec
349e0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
349f0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76  qlite3_module {v
34a00 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
34a10 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ule}.**.** This 
34a20 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74  structure, somet
34a30 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 22 76  imes called a "v
34a40 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
34a50 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65  ule", .** define
34a60 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  s the implementa
34a70 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75  tion of a [virtu
34a80 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a  al tables].  .**
34a90 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20   This structure 
34aa0 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20  consists mostly 
34ab0 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74  of methods for t
34ac0 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a  he module..**.**
34ad0 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c   ^A virtual tabl
34ae0 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61  e module is crea
34af0 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69  ted by filling i
34b00 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  n a persistent.*
34b10 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
34b20 69 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64  is structure and
34b30 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74   passing a point
34b40 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61  er to that insta
34b50 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  nce.** to [sqlit
34b60 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
34b70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
34b80 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
34b90 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67  ()]..** ^The reg
34ba0 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e  istration remain
34bb0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74  s valid until it
34bc0 20 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20   is replaced by 
34bd0 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d  a different.** m
34be0 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74  odule or until t
34bf0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34c00 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e  nection] closes.
34c10 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a    The content.**
34c20 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
34c30 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e  re must not chan
34c40 67 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72  ge while it is r
34c50 65 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a  egistered with.*
34c60 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  * any database c
34c70 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74  onnection..*/.st
34c80 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
34c90 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ule {.  int iVer
34ca0 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
34cb0 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c  reate)(sqlite3*,
34cc0 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
34cd0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
34ce0 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
34cf0 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
34d00 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
34d10 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
34d20 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
34d30 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73  nt (*xConnect)(s
34d40 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
34d50 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
34d60 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
34d70 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
34d80 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
34d90 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
34da0 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
34db0 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65  **);.  int (*xBe
34dc0 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33  stIndex)(sqlite3
34dd0 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
34de0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
34df0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73  *);.  int (*xDis
34e00 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  connect)(sqlite3
34e10 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
34e20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29   int (*xDestroy)
34e30 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
34e40 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
34e50 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  Open)(sqlite3_vt
34e60 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
34e70 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a  e3_vtab_cursor *
34e80 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e  *ppCursor);.  in
34e90 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
34ea0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
34eb0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74  );.  int (*xFilt
34ec0 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  er)(sqlite3_vtab
34ed0 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64  _cursor*, int id
34ee0 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72  xNum, const char
34ef0 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20   *idxStr,.      
34f00 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
34f10 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  gc, sqlite3_valu
34f20 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74  e **argv);.  int
34f30 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65   (*xNext)(sqlite
34f40 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
34f50 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73  .  int (*xEof)(s
34f60 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
34f70 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  or*);.  int (*xC
34f80 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76  olumn)(sqlite3_v
34f90 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
34fa0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
34fb0 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  nt);.  int (*xRo
34fc0 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61  wid)(sqlite3_vta
34fd0 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74  b_cursor*, sqlit
34fe0 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64  e3_int64 *pRowid
34ff0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61  );.  int (*xUpda
35000 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  te)(sqlite3_vtab
35010 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33   *, int, sqlite3
35020 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74  _value **, sqlit
35030 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69  e3_int64 *);.  i
35040 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c  nt (*xBegin)(sql
35050 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
35060 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
35070 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
35080 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
35090 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33  xCommit)(sqlite3
350a0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
350b0 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
350c0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
350d0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
350e0 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73  xFindFunction)(s
350f0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
35100 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f  ab, int nArg, co
35110 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
35120 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
35130 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a          void (**
35140 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  pxFunc)(sqlite3_
35150 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
35160 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35180 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41        void **ppA
35190 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  rg);.  int (*xRe
351a0 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74  name)(sqlite3_vt
351b0 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74  ab *pVtab, const
351c0 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b   char *zNew);.};
351d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
351e0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
351f0 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61  Indexing Informa
35200 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  tion.** KEYWORDS
35210 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  : sqlite3_index_
35220 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  info.**.** The s
35230 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
35240 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  o structure and 
35250 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65  its substructure
35260 73 20 69 73 20 75 73 65 64 20 61 73 20 70 61 72  s is used as par
35270 74 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72  t.** of the [vir
35280 74 75 61 6c 20 74 61 62 6c 65 5d 20 69 6e 74 65  tual table] inte
35290 72 66 61 63 65 20 74 6f 0a 2a 2a 20 70 61 73 73  rface to.** pass
352a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74   information int
352b0 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68  o and receive th
352c0 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65  e reply from the
352d0 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a   [xBestIndex].**
352e0 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69   method of a [vi
352f0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
35300 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73  le].  The fields
35310 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a   under **Inputs*
35320 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70  * are the.** inp
35330 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65  uts to xBestInde
35340 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f  x and are read-o
35350 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78  nly.  xBestIndex
35360 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20   inserts its.** 
35370 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65  results into the
35380 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65   **Outputs** fie
35390 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  lds..**.** ^(The
353a0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
353b0 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45  rray records WHE
353c0 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
353d0 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72  aints of the for
353e0 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  m:.**.** <blockq
353f0 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65  uote>column OP e
35400 78 70 72 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  xpr</blockquote>
35410 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20  .**.** where OP 
35420 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b  is =, &lt;, &lt;
35430 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b  =, &gt;, or &gt;
35440 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74  =.)^  ^(The part
35450 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20  icular operator 
35460 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20  is.** stored in 
35470 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70  aConstraint[].op
35480 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
35490 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 44  e.** [SQLITE_IND
354a0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51  EX_CONSTRAINT_EQ
354b0 20 7c 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f   | SQLITE_INDEX_
354c0 43 4f 4e 53 54 52 41 49 4e 54 5f 20 76 61 6c 75  CONSTRAINT_ valu
354d0 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20  es].)^.** ^(The 
354e0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
354f0 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e  umn is stored in
35500 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  .** aConstraint[
35510 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28  ].iColumn.)^  ^(
35520 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73  aConstraint[].us
35530 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20  able is TRUE if 
35540 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74  the.** expr on t
35550 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
35560 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61  de can be evalua
35570 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68  ted (and thus th
35580 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  e constraint.** 
35590 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66  is usable) and f
355a0 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f  alse if it canno
355b0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  t.)^.**.** ^The 
355c0 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61  optimizer automa
355d0 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20  tically inverts 
355e0 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72  terms of the for
355f0 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d  m "expr OP colum
35600 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20  n".** and makes 
35610 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61  other simplifica
35620 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45  tions to the WHE
35630 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20  RE clause in an 
35640 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65  attempt to.** ge
35650 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20  t as many WHERE 
35660 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74  clause terms int
35670 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e  o the form shown
35680 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62   above as possib
35690 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e  le..** ^The aCon
356a0 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
356b0 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45  only reports WHE
356c0 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
356d0 74 68 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65  that are.** rele
356e0 76 61 6e 74 20 74 6f 20 74 68 65 20 70 61 72 74  vant to the part
356f0 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74  icular virtual t
35700 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69  able being queri
35710 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72  ed..**.** ^Infor
35720 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
35730 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
35740 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
35750 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61  rderBy[]..** ^Ea
35760 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
35770 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
35780 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
35790 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
357a0 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64  ** The [xBestInd
357b0 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  ex] method must 
357c0 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74  fill aConstraint
357d0 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66  Usage[] with inf
357e0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
357f0 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72  t what parameter
35800 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69  s to pass to xFi
35810 6c 74 65 72 2e 20 20 5e 49 66 20 61 72 67 76 49  lter.  ^If argvI
35820 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74  ndex>0 then.** t
35830 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69  he right-hand si
35840 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73  de of the corres
35850 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61  ponding aConstra
35860 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74  int[] is evaluat
35870 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65  ed.** and become
35880 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d  s the argvIndex-
35890 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76  th entry in argv
358a0 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61  .  ^(If aConstra
358b0 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a  intUsage[].omit.
358c0 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  ** is true, then
358d0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
358e0 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65  is assumed to be
358f0 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62   fully handled b
35900 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c  y the.** virtual
35910 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f   table and is no
35920 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20  t checked again 
35930 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a  by SQLite.)^.**.
35940 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75 6d 20 61  ** ^The idxNum a
35950 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
35960 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
35970 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  d passed into th
35980 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d  e.** [xFilter] m
35990 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69  ethod..** ^[sqli
359a0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75  te3_free()] is u
359b0 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50  sed to free idxP
359c0 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  tr if and only i
359d0 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49  f.** needToFreeI
359e0 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
359f0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72 42  *.** ^The orderB
35a00 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20  yConsumed means 
35a10 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d  that output from
35a20 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78   [xFilter]/[xNex
35a30 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e  t] will occur in
35a40 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20  .** the correct 
35a50 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79  order to satisfy
35a60 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
35a70 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20  ause so that no 
35a80 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74  separate.** sort
35a90 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75  ing step is requ
35aa0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
35ab0 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76   estimatedCost v
35ac0 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d  alue is an estim
35ad0 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20  ate of the cost 
35ae0 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20  of doing the.** 
35af0 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75  particular looku
35b00 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20  p.  A full scan 
35b10 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20  of a table with 
35b20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
35b30 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20   have.** a cost 
35b40 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20  of N.  A binary 
35b50 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c  search of a tabl
35b60 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73  e of N entries s
35b70 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20  hould have a.** 
35b80 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d  cost of approxim
35b90 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f  ately log(N)..*/
35ba0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
35bb0 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f  index_info {.  /
35bc0 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e  * Inputs */.  in
35bd0 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20  t nConstraint;  
35be0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
35bf0 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e  er of entries in
35c00 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a   aConstraint */.
35c10 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
35c20 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e  _index_constrain
35c30 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  t {.     int iCo
35c40 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
35c50 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20     /* Column on 
35c60 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
35c70 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  f constraint */.
35c80 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
35c90 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f  ar op;         /
35ca0 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65  * Constraint ope
35cb0 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e  rator */.     un
35cc0 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62  signed char usab
35cd0 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20  le;     /* True 
35ce0 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  if this constrai
35cf0 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a  nt is usable */.
35d00 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66       int iTermOf
35d10 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f  fset;          /
35d20 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  * Used internall
35d30 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73  y - xBestIndex s
35d40 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a  hould ignore */.
35d50 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74    } *aConstraint
35d60 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
35d70 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63  Table of WHERE c
35d80 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
35d90 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65  s */.  int nOrde
35da0 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20  rBy;            
35db0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74    /* Number of t
35dc0 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45  erms in the ORDE
35dd0 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20  R BY clause */. 
35de0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
35df0 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a  index_orderby {.
35e00 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
35e10 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
35e20 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20  * Column number 
35e30 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
35e40 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20   char desc;     
35e50 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45    /* True for DE
35e60 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41  SC.  False for A
35e70 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64  SC. */.  } *aOrd
35e80 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
35e90 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52      /* The ORDER
35ea0 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20   BY clause */.  
35eb0 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20  /* Outputs */.  
35ec0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
35ed0 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f  ndex_constraint_
35ee0 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20  usage {.    int 
35ef0 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20  argvIndex;      
35f00 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63       /* if >0, c
35f10 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72  onstraint is par
35f20 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69  t of argv to xFi
35f30 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69  lter */.    unsi
35f40 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20  gned char omit; 
35f50 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63       /* Do not c
35f60 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74  ode a test for t
35f70 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a  his constraint *
35f80 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69  /.  } *aConstrai
35f90 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69  ntUsage;.  int i
35fa0 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20  dxNum;          
35fb0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
35fc0 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79  used to identify
35fd0 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20   the index */.  
35fe0 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20  char *idxStr;   
35ff0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
36000 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f  ring, possibly o
36010 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
36020 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20  ite3_malloc */. 
36030 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49   int needToFreeI
36040 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46  dxStr;      /* F
36050 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e 67  ree idxStr using
36060 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
36070 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74  if true */.  int
36080 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64   orderByConsumed
36090 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20  ;       /* True 
360a0 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72  if output is alr
360b0 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a  eady ordered */.
360c0 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74    double estimat
360d0 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20  edCost;      /* 
360e0 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f  Estimated cost o
360f0 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64  f using this ind
36100 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ex */.};../*.** 
36110 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
36120 6c 20 54 61 62 6c 65 20 43 6f 6e 73 74 72 61 69  l Table Constrai
36130 6e 74 20 4f 70 65 72 61 74 6f 72 20 43 6f 64 65  nt Operator Code
36140 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61  s.**.** These ma
36150 63 72 6f 73 20 64 65 66 69 6e 65 64 20 74 68 65  cros defined the
36160 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20   allowed values 
36170 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  for the.** [sqli
36180 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 5d 2e  te3_index_info].
36190 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70  aConstraint[].op
361a0 20 66 69 65 6c 64 2e 20 20 45 61 63 68 20 76 61   field.  Each va
361b0 6c 75 65 20 72 65 70 72 65 73 65 6e 74 73 0a 2a  lue represents.*
361c0 2a 20 61 6e 20 6f 70 65 72 61 74 6f 72 20 74 68  * an operator th
361d0 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20  at is part of a 
361e0 63 6f 6e 73 74 72 61 69 6e 74 20 74 65 72 6d 20  constraint term 
361f0 69 6e 20 74 68 65 20 77 48 45 52 45 20 63 6c 61  in the wHERE cla
36200 75 73 65 20 6f 66 0a 2a 2a 20 61 20 71 75 65 72  use of.** a quer
36210 79 20 74 68 61 74 20 75 73 65 73 20 61 20 5b 76  y that uses a [v
36220 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a  irtual table]..*
36230 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36240 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
36250 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e  T_EQ    2.#defin
36260 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
36270 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20  ONSTRAINT_GT    
36280 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
36290 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
362a0 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e  T_LE    8.#defin
362b0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
362c0 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20  ONSTRAINT_LT    
362d0 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
362e0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
362f0 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66  NT_GE    32.#def
36300 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
36310 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43  _CONSTRAINT_MATC
36320 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  H 64../*.** CAPI
36330 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
36340 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
36350 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
36360 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
36370 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  nes are used to 
36380 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b  register a new [
36390 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
363a0 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  dule] name..** ^
363b0 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
363c0 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
363d0 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69  before.** creati
363e0 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  ng a new [virtua
363f0 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74  l table] using t
36400 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65  he module and be
36410 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20  fore using a.** 
36420 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72  preexisting [vir
36430 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20  tual table] for 
36440 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a  the module..**.*
36450 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61  * ^The module na
36460 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64  me is registered
36470 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
36480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
36490 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
364a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
364b0 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  r.  ^The name of
364c0 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67   the module is g
364d0 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20  iven by the .** 
364e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
364f0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
36500 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
36510 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69  nter to.** the i
36520 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
36530 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
36540 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e  ble module].   ^
36550 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61  The fourth.** pa
36560 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
36570 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64  bitrary client d
36580 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
36590 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
365a0 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b  gh.** into the [
365b0 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43  xCreate] and [xC
365c0 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20  onnect] methods 
365d0 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
365e0 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77  able module.** w
365f0 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61  hen a new virtua
36600 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65  l table is be be
36610 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72  ing created or r
36620 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a  einitialized..**
36630 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36640 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
36650 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61  2() interface ha
36660 73 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65  s a fifth parame
36670 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
36680 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64  a pointer to a d
36690 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
366a0 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20  e pClientData.  
366b0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20  ^SQLite will.** 
366c0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
366d0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28  uctor function (
366e0 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  if it is not NUL
366f0 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a  L) when SQLite.*
36700 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  * no longer need
36710 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  s the pClientDat
36720 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  a pointer.  ^The
36730 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
36740 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 69 6e 76 6f   also.** be invo
36750 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
36760 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
36770 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 66 61  e_module_v2() fa
36780 69 6c 73 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ils..** ^The sql
36790 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
367a0 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  le().** interfac
367b0 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  e is equivalent 
367c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
367d0 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77 69  e_module_v2() wi
367e0 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73  th a NULL.** des
367f0 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20  tructor..*/.int 
36800 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
36810 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  odule(.  sqlite3
36820 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
36830 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
36840 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
36850 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
36860 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
36870 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
36880 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
36890 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
368a0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
368b0 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *p,   /* Method
368c0 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
368d0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69   */.  void *pCli
368e0 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20 20  entData         
368f0 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
36900 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
36910 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  nect */.);.int s
36920 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
36930 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  dule_v2(.  sqlit
36940 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
36950 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
36960 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
36970 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
36980 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
36990 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
369a0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
369b0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
369c0 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
369d0 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68  le *p,   /* Meth
369e0 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
369f0 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43  le */.  void *pC
36a00 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20  lientData,      
36a10 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
36a20 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
36a30 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64  onnect */.  void
36a40 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
36a50 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65  *)     /* Module
36a60 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
36a70 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  tion */.);../*.*
36a80 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
36a90 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e  ual Table Instan
36aa0 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ce Object.** KEY
36ab0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
36ac0 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  tab.**.** Every 
36ad0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
36ae0 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74  odule] implement
36af0 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
36b00 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73  class.** of this
36b10 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63 72   object to descr
36b20 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72  ibe a particular
36b30 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20   instance.** of 
36b40 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
36b50 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63 6c  le].  Each subcl
36b60 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74  ass will.** be t
36b70 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73  ailored to the s
36b80 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
36b90 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   the module impl
36ba0 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54  ementation..** T
36bb0 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68  he purpose of th
36bc0 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73  is superclass is
36bd0 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61   to define certa
36be0 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61  in fields that a
36bf0 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20  re.** common to 
36c00 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  all module imple
36c10 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  mentations..**.*
36c20 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c 65  * ^Virtual table
36c30 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65  s methods can se
36c40 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  t an error messa
36c50 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20  ge by assigning 
36c60 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61  a.** string obta
36c70 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
36c80 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f  e3_mprintf()] to
36c90 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d   zErrMsg.  The m
36ca0 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20  ethod should.** 
36cb0 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61  take care that a
36cc0 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20  ny prior string 
36cd0 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61  is freed by a ca
36ce0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ll to [sqlite3_f
36cf0 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20  ree()].** prior 
36d00 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
36d10 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
36d20 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74 68  rMsg.  ^After th
36d30 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  e error message.
36d40 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20  ** is delivered 
36d50 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74  up to the client
36d60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
36d70 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
36d80 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
36d90 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74  * freed by sqlit
36da0 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68  e3_free() and th
36db0 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20  e zErrMsg field 
36dc0 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a  will be zeroed..
36dd0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
36de0 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74  3_vtab {.  const
36df0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
36e00 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68  *pModule;  /* Th
36e10 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69  e module for thi
36e20 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  s virtual table 
36e30 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20  */.  int nRef;  
36e40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36e50 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45       /* NO LONGE
36e60 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72  R USED */.  char
36e70 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20   *zErrMsg;      
36e80 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
36e90 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f  rror message fro
36ea0 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
36eb0 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  f() */.  /* Virt
36ec0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
36ed0 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
36ee0 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
36ef0 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
36f00 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
36f10 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
36f20 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63  ble Cursor Objec
36f30 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
36f40 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
36f50 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  or {virtual tabl
36f60 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20  e cursor}.**.** 
36f70 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
36f80 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
36f90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
36fa0 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
36fb0 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
36fc0 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73  structure to des
36fd0 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68  cribe cursors th
36fe0 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68  at point into th
36ff0 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  e.** [virtual ta
37000 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65  ble] and are use
37010 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72  d.** to loop thr
37020 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c  ough the virtual
37030 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73   table.  Cursors
37040 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
37050 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
37060 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20  e3_module.xOpen 
37070 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  | xOpen] method 
37080 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e  of the module an
37090 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a  d are destroyed.
370a0 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ** by the [sqlit
370b0 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65  e3_module.xClose
370c0 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f   | xClose] metho
370d0 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  d.  Cursors are 
370e0 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  used.** by the [
370f0 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74  xFilter], [xNext
37100 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c  ], [xEof], [xCol
37110 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69  umn], and [xRowi
37120 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  d] methods.** of
37130 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61   the module.  Ea
37140 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ch module implem
37150 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65  entation will de
37160 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  fine.** the cont
37170 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20  ent of a cursor 
37180 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69  structure to sui
37190 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e  t its own needs.
371a0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65  .**.** This supe
371b0 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e  rclass exists in
371c0 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65   order to define
371d0 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63   fields of the c
371e0 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72  ursor that.** ar
371f0 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  e common to all 
37200 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
37210 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
37220 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
37230 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  .  sqlite3_vtab 
37240 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20  *pVtab;      /* 
37250 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66  Virtual table of
37260 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a   this cursor */.
37270 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
37280 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
37290 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
372a0 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
372b0 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
372c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
372d0 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d  eclare The Schem
372e0 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54  a Of A Virtual T
372f0 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  able.**.** ^The 
37300 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78  [xCreate] and [x
37310 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73  Connect] methods
37320 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61   of a.** [virtua
37330 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
37340 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66  call this interf
37350 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72  ace.** to declar
37360 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68  e the format (th
37370 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  e names and data
37380 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  types of the col
37390 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20  umns) of.** the 
373a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74  virtual tables t
373b0 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a  hey implement..*
373c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65  /.int sqlite3_de
373d0 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74  clare_vtab(sqlit
373e0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
373f0 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *zSQL);../*.** C
37400 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61  API3REF: Overloa
37410 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72  d A Function For
37420 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
37430 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c  .**.** ^(Virtual
37440 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76   tables can prov
37450 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ide alternative 
37460 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37470 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
37480 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64  using the [xFind
37490 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64  Function] method
374a0 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
374b0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
374c0 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20   .** But global 
374d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73  versions of thos
374e0 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d  e functions.** m
374f0 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64  ust exist in ord
37500 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61  er to be overloa
37510 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ded.)^.**.** ^(T
37520 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75  his API makes su
37530 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73  re a global vers
37540 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f  ion of a functio
37550 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  n with a particu
37560 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20  lar.** name and 
37570 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
37580 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66  ters exists.  If
37590 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f   no such functio
375a0 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f  n exists.** befo
375b0 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63  re this API is c
375c0 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e  alled, a new fun
375d0 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
375e0 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d  .)^  ^The implem
375f0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
37600 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20  he new function 
37610 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 6e  always causes an
37620 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65   exception to be
37630 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20   thrown.  So.** 
37640 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
37650 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72   is not good for
37660 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73   anything by its
37670 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a  elf.  Its only.*
37680 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20  * purpose is to 
37690 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72  be a placeholder
376a0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63   function that c
376b0 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  an be overloaded
376c0 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75 61  .** by a [virtua
376d0 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74  l table]..*/.int
376e0 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61   sqlite3_overloa
376f0 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74  d_function(sqlit
37700 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
37710 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20  *zFuncName, int 
37720 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  nArg);../*.** Th
37730 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
37740 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
37750 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e   mechanism defin
37760 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75  ed above (back u
37770 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e  p.** to a commen
37780 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d  t remarkably sim
37790 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65  ilar to this one
377a0 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  ) is currently c
377b0 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
377c0 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
377d0 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
377e0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
377f0 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
37800 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
37810 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
37820 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
37830 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
37840 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
37850 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
37860 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
37870 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
37880 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
37890 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
378a0 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
378b0 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
378c0 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
378d0 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a  omment..*/../*.*
378e0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61  * CAPI3REF: A Ha
378f0 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20  ndle To An Open 
37900 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  BLOB.** KEYWORDS
37910 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20  : {BLOB handle} 
37920 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a  {BLOB handles}.*
37930 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
37940 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
37950 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
37960 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68  en BLOB on which
37970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
37980 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
37990 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63  ntal BLOB I/O] c
379a0 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e  an be performed.
379b0 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20  .** ^Objects of 
379c0 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72  this type are cr
379d0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
379e0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a  3_blob_open()].*
379f0 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20  * and destroyed 
37a00 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
37a10 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54  _close()]..** ^T
37a20 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
37a30 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
37a40 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
37a50 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
37a60 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
37a70 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73   read or write s
37a80 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73  mall subsections
37a90 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a   of the BLOB..**
37aa0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
37ab0 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
37ac0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
37ad0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42  he size of the B
37ae0 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  LOB in bytes..*/
37af0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
37b00 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
37b10 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
37b20 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
37b30 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
37b40 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a  emental I/O.**.*
37b50 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
37b60 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f  ces opens a [BLO
37b70 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c  B handle | handl
37b80 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c  e] to the BLOB l
37b90 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77  ocated.** in row
37ba0 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43   iRow, column zC
37bb0 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61  olumn, table zTa
37bc0 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20  ble in database 
37bd0 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72  zDb;.** in other
37be0 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65   words, the same
37bf0 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64   BLOB that would
37c00 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a   be selected by:
37c10 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
37c20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75      SELECT zColu
37c30 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62  mn FROM zDb.zTab
37c40 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d  le WHERE [rowid]
37c50 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72   = iRow;.** </pr
37c60 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  e>)^.**.** ^If t
37c70 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
37c80 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
37c90 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  then the BLOB is
37ca0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
37cb0 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63  .** and write ac
37cc0 63 65 73 73 2e 20 5e 49 66 20 69 74 20 69 73 20  cess. ^If it is 
37cd0 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69  zero, the BLOB i
37ce0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
37cf0 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 74  d access..** ^It
37d00 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
37d10 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d   to open a colum
37d20 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  n that is part o
37d30 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72  f an index or pr
37d40 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f  imary .** key fo
37d50 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b  r writing. ^If [
37d60 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
37d70 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61  traints] are ena
37d80 62 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20  bled, it is .** 
37d90 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
37da0 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68  open a column th
37db0 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20  at is part of a 
37dc0 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20  [child key] for 
37dd0 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  writing..**.** ^
37de0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61  Note that the da
37df0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e  tabase name is n
37e00 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ot the filename 
37e10 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  that contains.**
37e20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
37e30 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d  t rather the sym
37e40 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68  bolic name of th
37e50 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a  e database that.
37e60 2a 2a 20 61 70 70 65 61 72 73 20 61 66 74 65 72  ** appears after
37e70 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20   the AS keyword 
37e80 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
37e90 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75  e is connected u
37ea0 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a  sing [ATTACH]..*
37eb0 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61 69 6e 20  * ^For the main 
37ec0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74  database file, t
37ed0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
37ee0 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e   is "main"..** ^
37ef0 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c  For TEMP tables,
37f00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
37f10 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a  me is "temp"..**
37f20 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73  .** ^(On success
37f30 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
37f40 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68   returned and th
37f50 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64  e new [BLOB hand
37f60 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  le] is written.*
37f70 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74  * to *ppBlob. Ot
37f80 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
37f90 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
37fa0 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20  ned and *ppBlob 
37fb0 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20  is set.** to be 
37fc0 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 29  a null pointer.)
37fd0 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  ^.** ^This funct
37fe0 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61  ion sets the [da
37ff0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38000 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  n] error code an
38010 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
38020 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
38030 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
38040 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
38050 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c 61 74  msg()] and relat
38060 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e  ed.** functions.
38070 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
38080 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c 65  *ppBlob variable
38090 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69 74 69   is always initi
380a0 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77  alized in a.** w
380b0 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74  ay that makes it
380c0 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20   safe to invoke 
380d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
380e0 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f  ose()] on *ppBlo
380f0 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  b.** regardless 
38100 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 20 6f  of the success o
38110 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 69  r failure of thi
38120 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a  s routine..**.**
38130 20 5e 28 49 66 20 74 68 65 20 72 6f 77 20 74 68   ^(If the row th
38140 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65  at a BLOB handle
38150 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f   points to is mo
38160 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20  dified by an.** 
38170 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54  [UPDATE], [DELET
38180 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f  E], or by [ON CO
38190 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66  NFLICT] side-eff
381a0 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ects.** then the
381b0 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20   BLOB handle is 
381c0 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 69 72  marked as "expir
381d0 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ed"..** This is 
381e0 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75  true if any colu
381f0 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73  mn of the row is
38200 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61   changed, even a
38210 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72   column.** other
38220 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68   than the one th
38230 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73  e BLOB handle is
38240 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e   open on.)^.** ^
38250 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
38260 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
38270 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
38280 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a  _write()] for.**
38290 20 61 6e 20 65 78 70 69 72 65 64 20 42 4c 4f 42   an expired BLOB
382a0 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74   handle fail wit
382b0 68 20 61 20 72 65 74 75 72 6e 20 63 6f 64 65 20  h a return code 
382c0 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
382d0 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 73 20  ]..** ^(Changes 
382e0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42  written into a B
382f0 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65  LOB prior to the
38300 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61   BLOB expiring a
38310 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64  re not.** rolled
38320 20 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70   back by the exp
38330 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42  iration of the B
38340 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67  LOB.  Such chang
38350 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  es will eventual
38360 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20  ly.** commit if 
38370 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
38380 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
38390 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  pletion.)^.**.**
383a0 20 5e 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74   ^Use the [sqlit
383b0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
383c0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65   interface to de
383d0 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65  termine the size
383e0 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65   of.** the opene
383f0 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69  d blob.  ^The si
38400 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79  ze of a blob may
38410 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20   not be changed 
38420 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  by this.** inter
38430 66 61 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b  face.  Use the [
38440 55 50 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d  UPDATE] SQL comm
38450 61 6e 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  and to change th
38460 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62  e size of a.** b
38470 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lob..**.** ^The 
38480 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65  [sqlite3_bind_ze
38490 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73  roblob()] and [s
384a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
384b0 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66  roblob()] interf
384c0 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20  aces.** and the 
384d0 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c  built-in [zerobl
384e0 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ob] SQL function
384f0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 69 66   can be used, if
38500 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20   desired,.** to 
38510 63 72 65 61 74 65 20 61 6e 20 65 6d 70 74 79 2c  create an empty,
38520 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f   zero-filled blo
38530 62 20 69 6e 20 77 68 69 63 68 20 74 6f 20 72 65  b in which to re
38540 61 64 20 6f 72 20 77 72 69 74 65 20 75 73 69 6e  ad or write usin
38550 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  g.** this interf
38560 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76  ace..**.** To av
38570 6f 69 64 20 61 20 72 65 73 6f 75 72 63 65 20 6c  oid a resource l
38580 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e 20  eak, every open 
38590 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68  [BLOB handle] sh
385a0 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a  ould eventually.
385b0 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ** be released b
385c0 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
385d0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
385e0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
385f0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20  e3_blob_open(.  
38600 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73  sqlite3*,.  cons
38610 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63  t char *zDb,.  c
38620 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
38630 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e,.  const char 
38640 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69  *zColumn,.  sqli
38650 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a  te3_int64 iRow,.
38660 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73    int flags,.  s
38670 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70  qlite3_blob **pp
38680 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Blob.);../*.** C
38690 41 50 49 33 52 45 46 3a 20 4d 6f 76 65 20 61 20  API3REF: Move a 
386a0 42 4c 4f 42 20 48 61 6e 64 6c 65 20 74 6f 20 61  BLOB Handle to a
386b0 20 4e 65 77 20 52 6f 77 0a 2a 2a 0a 2a 2a 20 5e   New Row.**.** ^
386c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
386d0 20 75 73 65 64 20 74 6f 20 6d 6f 76 65 20 61 6e   used to move an
386e0 20 65 78 69 73 74 69 6e 67 20 62 6c 6f 62 20 68   existing blob h
386f0 61 6e 64 6c 65 20 73 6f 20 74 68 61 74 20 69 74  andle so that it
38700 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20   points.** to a 
38710 64 69 66 66 65 72 65 6e 74 20 72 6f 77 20 6f 66  different row of
38720 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
38730 73 65 20 74 61 62 6c 65 2e 20 5e 54 68 65 20 6e  se table. ^The n
38740 65 77 20 72 6f 77 20 69 73 20 69 64 65 6e 74 69  ew row is identi
38750 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 72  fied.** by the r
38760 6f 77 69 64 20 76 61 6c 75 65 20 70 61 73 73 65  owid value passe
38770 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
38780 61 72 67 75 6d 65 6e 74 2e 20 4f 6e 6c 79 20 74  argument. Only t
38790 68 65 20 72 6f 77 20 63 61 6e 20 62 65 0a 2a 2a  he row can be.**
387a0 20 63 68 61 6e 67 65 64 2e 20 5e 54 68 65 20 64   changed. ^The d
387b0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61  atabase, table a
387c0 6e 64 20 63 6f 6c 75 6d 6e 20 6f 6e 20 77 68 69  nd column on whi
387d0 63 68 20 74 68 65 20 62 6c 6f 62 20 68 61 6e 64  ch the blob hand
387e0 6c 65 20 69 73 20 6f 70 65 6e 0a 2a 2a 20 72 65  le is open.** re
387f0 6d 61 69 6e 20 74 68 65 20 73 61 6d 65 2e 20 4d  main the same. M
38800 6f 76 69 6e 67 20 61 6e 20 65 78 69 73 74 69 6e  oving an existin
38810 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 74 6f  g blob handle to
38820 20 61 20 6e 65 77 20 72 6f 77 20 63 61 6e 20 62   a new row can b
38830 65 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 61 6e  e.** faster than
38840 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 65 78 69   closing the exi
38850 73 74 69 6e 67 20 68 61 6e 64 6c 65 20 61 6e 64  sting handle and
38860 20 6f 70 65 6e 69 6e 67 20 61 20 6e 65 77 20 6f   opening a new o
38870 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ne..**.** ^(The 
38880 6e 65 77 20 72 6f 77 20 6d 75 73 74 20 6d 65 65  new row must mee
38890 74 20 74 68 65 20 73 61 6d 65 20 63 72 69 74 65  t the same crite
388a0 72 69 61 20 61 73 20 66 6f 72 20 5b 73 71 6c 69  ria as for [sqli
388b0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
388c0 20