/ Hex Artifact Content
Login

Artifact 3ccf717d82101f19548d0b1243f0a6f4854d51ee:


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 20 7b 48 31 30 30 31 30 7d 20 3c 53 36 30  rs {H10010} <S60
0ac0: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  100>.**.** The S
0ad0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e  QLITE_VERSION an
0ae0: 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  d SQLITE_VERSION
0af0: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73  _NUMBER #defines
0b00: 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74   in.** the sqlit
0b10: 65 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66  e3.h file specif
0b20: 79 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66  y the version of
0b30: 20 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69   SQLite with whi
0b40: 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65  ch.** that heade
0b50: 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69  r file is associ
0b60: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
0b70: 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c  "version" of SQL
0b80: 69 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  ite is a string 
0b90: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 58 2e 59  of the form "X.Y
0ba0: 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 70 68 72 61  .Z"..** The phra
0bb0: 73 65 20 22 61 6c 70 68 61 22 20 6f 72 20 22 62  se "alpha" or "b
0bc0: 65 74 61 22 20 6d 69 67 68 74 20 62 65 20 61 70  eta" might be ap
0bd0: 70 65 6e 64 65 64 20 61 66 74 65 72 20 74 68 65  pended after the
0be0: 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c   Z..** The X val
0bf0: 75 65 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73  ue is major vers
0c00: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6c 77 61 79  ion number alway
0c10: 73 20 33 20 69 6e 20 53 51 4c 69 74 65 33 2e 0a  s 3 in SQLite3..
0c20: 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 6f  ** The X value o
0c30: 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e  nly changes when
0c40: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
0c50: 74 69 62 69 6c 69 74 79 20 69 73 0a 2a 2a 20 62  tibility is.** b
0c60: 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69 6e 74  roken and we int
0c70: 65 6e 64 20 74 6f 20 6e 65 76 65 72 20 62 72 65  end to never bre
0c80: 61 6b 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ak backwards com
0c90: 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 54  patibility..** T
0ca0: 68 65 20 59 20 76 61 6c 75 65 20 69 73 20 74 68  he Y value is th
0cb0: 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20  e minor version 
0cc0: 6e 75 6d 62 65 72 20 61 6e 64 20 6f 6e 6c 79 20  number and only 
0cd0: 63 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20  changes when.** 
0ce0: 74 68 65 72 65 20 61 72 65 20 6d 61 6a 6f 72 20  there are major 
0cf0: 66 65 61 74 75 72 65 20 65 6e 68 61 6e 63 65 6d  feature enhancem
0d00: 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 66 6f  ents that are fo
0d10: 72 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  rwards compatibl
0d20: 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 62 61 63  e.** but not bac
0d30: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  kwards compatibl
0d40: 65 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61 6c 75  e..** The Z valu
0d50: 65 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65  e is the release
0d60: 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20 69   number and is i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68 0a  ncremented with.
0d80: 2a 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65 20  ** each release 
0d90: 62 75 74 20 72 65 73 65 74 73 20 62 61 63 6b 20  but resets back 
0da0: 74 6f 20 30 20 77 68 65 6e 65 76 65 72 20 59 20  to 0 whenever Y 
0db0: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 0a  is incremented..
0dc0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
0dd0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0de0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  is an integer th
0df0: 61 74 20 69 73 20 63 6f 6d 70 75 74 65 64 20 61  at is computed a
0e00: 73 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s.** follows:.**
0e10: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
0e20: 3c 70 72 65 3e 0a 2a 2a 20 53 51 4c 49 54 45 5f  <pre>.** SQLITE_
0e30: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 3d  VERSION_NUMBER =
0e40: 20 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31   X*1000000 + Y*1
0e50: 30 30 30 20 2b 20 5a 0a 2a 2a 20 3c 2f 70 72 65  000 + Z.** </pre
0e60: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
0e70: 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69  *.** Since versi
0e80: 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74  on 3.6.18, SQLit
0e90: 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61  e source code ha
0ea0: 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e  s been stored in
0eb0: 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
0ec0: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73  "http://www.foss
0ed0: 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 66 6f 73  il-scm.org/">fos
0ee0: 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  sil configuratio
0ef0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20  n management.** 
0f00: 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 54 68 65  system</a>.  The
0f10: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0f20: 44 0a 2a 2a 20 6d 61 63 72 6f 20 69 73 20 61 20  D.** macro is a 
0f30: 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 65  string which ide
0f40: 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69 63  ntifies a partic
0f50: 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66  ular check-in of
0f60: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69   SQLite.** withi
0f70: 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74  n its configurat
0f80: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73  ion management s
0f90: 79 73 74 65 6d 2e 20 20 54 68 65 20 73 74 72 69  ystem.  The stri
0fa0: 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  ng contains the.
0fb0: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
0fc0: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e   of the check-in
0fd0: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48   (UTC) and an SH
0fe0: 41 31 20 68 61 73 68 20 6f 66 20 74 68 65 20 65  A1 hash of the e
0ff0: 6e 74 69 72 65 0a 2a 2a 20 73 6f 75 72 63 65 20  ntire.** source 
1000: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tree..**.** See 
1010: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c  also: [sqlite3_l
1020: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a  ibversion()],.**
1030: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
1040: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20  sion_number()], 
1050: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75  and [sqlite3_sou
1060: 72 63 65 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  rceid()]..**.** 
1070: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48  Requirements: [H
1080: 31 30 30 31 31 5d 20 5b 48 31 30 30 31 34 5d 0a  10011] [H10014].
1090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10a0: 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20  E_VERSION       
10b0: 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66   "--VERS--".#def
10c0: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
10d0: 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53  ON_NUMBER --VERS
10e0: 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65  ION-NUMBER--.#de
10f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1100: 43 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f  CE_ID      "--SO
1110: 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a  URCE-ID--"../*.*
1120: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
1130: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
1140: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31  sion Numbers {H1
1150: 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a  0020} <S60100>.*
1160: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
1170: 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a  te3_version.**.*
1180: 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63  * These interfac
1190: 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73  es provide the s
11a0: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
11b0: 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56  as the [SQLITE_V
11c0: 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c  ERSION],.** [SQL
11d0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
11e0: 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  ER], and [SQLITE
11f0: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23 64 65 66  _SOURCE_ID] #def
1200: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64  ines in the head
1210: 65 72 2c 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  er,.** but are a
1220: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1230: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1240: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
1250: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73   file.  Cautious
1260: 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  .** programmers 
1270: 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 6e  might include an
1280: 20 61 73 73 65 72 74 20 69 6e 20 74 68 65 69 72   assert in their
1290: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
12a0: 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73  verify that.** s
12b0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
12c0: 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79  n_number() alway
12d0: 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  s returns the va
12e0: 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56  lue.** [SQLITE_V
12f0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 61  ERSION_NUMBER] a
1300: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1310: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1320: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1330: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1340: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1350: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
1360: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1370: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1380: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1390: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
13a0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
13b0: 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   );.** </pre></b
13c0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
13d0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
13e0: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
13f0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  on returns the s
1400: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
1410: 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20  as is.** in the 
1420: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1430: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1440: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
1450: 20 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20   is provided.** 
1460: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1470: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
1480: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1490: 61 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73  ave direct acces
14a0: 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63  s to string.** c
14b0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14c0: 74 68 65 20 44 4c 4c 2e 20 20 53 69 6d 69 6c 61  the DLL.  Simila
14d0: 72 6c 79 2c 20 74 68 65 20 73 71 6c 69 74 65 33  rly, the sqlite3
14e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
14f0: 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tion.** returns 
1500: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
1510: 74 69 6f 6e 20 61 73 20 69 73 20 69 6e 20 74 68  tion as is in th
1520: 65 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  e [SQLITE_SOURCE
1530: 5f 49 44 5d 20 23 64 65 66 69 6e 65 20 6f 66 0a  _ID] #define of.
1540: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 20 66 69  ** the header fi
1550: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  le..**.** Requir
1560: 65 6d 65 6e 74 73 3a 20 5b 48 31 30 30 32 31 5d  ements: [H10021]
1570: 20 5b 48 31 30 30 32 32 5d 20 5b 48 31 30 30 32   [H10022] [H1002
1580: 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  3].*/.SQLITE_EXT
1590: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
15a0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
15b0: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
15c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
15d0: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
15e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
15f0: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
1600: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1610: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1620: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1630: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1640: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1650: 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31  Threadsafe {H101
1660: 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a  00} <S60100>.**.
1670: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1680: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1690: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
16a0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
16b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
16c0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
16d0: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
16e0: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
16f0: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1700: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1710: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1720: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1730: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1740: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1750: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1760: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1770: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1780: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1790: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
17a0: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
17b0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
17c0: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
17d0: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
17e0: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
17f0: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1800: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1810: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1820: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1830: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1840: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1850: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1860: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1870: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1880: 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  d..** The defaul
1890: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
18a0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
18b0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
18c0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
18d0: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
18e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
18f0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1900: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1910: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1920: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1930: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1940: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1950: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1960: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1970: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1980: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1990: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
19a0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
19b0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
19c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
19d0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
19e0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
19f0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1a00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
1a10: 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74  DSAFE=1 then mut
1a20: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1a30: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1a40: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1a50: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1a60: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1a70: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1a80: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
1a90: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
1aa0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
1ab0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
1ac0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1ad0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
1ae0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1af0: 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  ].  The return v
1b00: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e  alue of this fun
1b10: 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f  ction shows.** o
1b20: 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20  nly the default 
1b30: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
1b40: 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75  ting, not any ru
1b50: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a  n-time changes.*
1b60: 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  * to that settin
1b70: 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  g..**.** See the
1b80: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1b90: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
1ba0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
1bb0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1bc0: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
1bd0: 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 31 30 32  [H10101] [H10102
1be0: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1bf0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1c00: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c10: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1c20: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1c30: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1c40: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1c50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c60: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1c70: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1c80: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
1c90: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
1ca0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
1cb0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
1cc0: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
1cd0: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
1ce0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1cf0: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1d00: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1d10: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1d20: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1d30: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1d40: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1d50: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1d70: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1d80: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
1d90: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
1da0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
1db0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
1dc0: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
1dd0: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
1de0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1df0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e00: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1e10: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1e20: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1e30: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1e40: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1e50: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1e60: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1e70: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1e80: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1e90: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ea0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1eb0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1ec0: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1ed0: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1ee0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1ef0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1f00: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1f10: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1f20: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1f30: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1f40: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1f50: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1f60: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1f70: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1f80: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1f90: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1fa0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1fb0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1fc0: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1fd0: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1fe0: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1ff0: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
2000: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
2010: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
2020: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
2030: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
2040: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  nly..**.** Requi
2050: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31  rements: [H10201
2060: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69  ] [H10202].*/.#i
2070: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
2080: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
2090: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
20a0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
20b0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
20c0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
20d0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
20e0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
20f0: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
2100: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
2110: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
2120: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
2130: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
2140: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
2150: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2160: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
2170: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
2180: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
2190: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
21a0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
21b0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
21c0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
21d0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
21e0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
21f0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
2200: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
2210: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
2220: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
2230: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
2240: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
2250: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
2260: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
2270: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
2280: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
2290: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
22a0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
22b0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
22c0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
22d0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
22e0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
22f0: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
2300: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
2310: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2320: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2330: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2340: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2350: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
2360: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
2370: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2380: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
2390: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
23a0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
23b0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
23c0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
23d0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
23e0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
23f0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2400: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
2410: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
2420: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2430: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2440: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2450: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2460: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2470: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2480: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
2490: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
24a0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
24b0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
24c0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
24d0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
24e0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
24f0: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
2500: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
2510: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
2520: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2530: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2540: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2550: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2560: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2570: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2580: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
2590: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
25a0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
25b0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
25c0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
25d0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
25e0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
25f0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2600: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2610: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2620: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2630: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2640: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2650: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2660: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2670: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2680: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2690: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
26a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26b0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
26c0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
26d0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
26e0: 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b  s:.** [H12011] [
26f0: 48 31 32 30 31 32 5d 20 5b 48 31 32 30 31 33 5d  H12012] [H12013]
2700: 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 32 30 31   [H12014] [H1201
2710: 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69  5] [H12019].*/.i
2720: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2730: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2740: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2750: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2760: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2770: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2780: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
2790: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
27a0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
27b0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
27c0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
27d0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
27e0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
27f0: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2800: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2810: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2820: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2830: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2840: 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30   {H12100} <S1000
2850: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2860: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2870: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
2880: 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e  nient way of run
2890: 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ning one or more
28a0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
28b0: 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ts without havin
28c0: 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74  g to write a lot
28d0: 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65   of C code.  The
28e0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a   UTF-8 encoded.*
28f0: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2900: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2910: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2920: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2930: 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65  3_exec()..** The
2940: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2950: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2960: 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65   one until eithe
2970: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a  r an error or.**
2980: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
2990: 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72   encountered, or
29a0: 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20   until they are 
29b0: 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33  all done.  The 3
29c0: 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
29d0: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63  is an optional c
29e0: 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20  allback that is 
29f0: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2a00: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79   each row of any
2a10: 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74   query.** result
2a20: 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68  s produced by th
2a30: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2a40: 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
2a50: 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65  eter tells where
2a60: 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79  .** to write any
2a70: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e   error messages.
2a80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72  .**.** The error
2a90: 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20   message passed 
2aa0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
2ab0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69   5th parameter i
2ac0: 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d  s held.** in mem
2ad0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2ae0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2af0: 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20  c()].  To avoid 
2b00: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a  a memory leak,.*
2b10: 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70  * the calling ap
2b20: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
2b30: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
2b40: 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72  ree()] on any er
2b50: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72  ror.** message r
2b60: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
2b70: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2b80: 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
2b90: 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
2ba0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2bb0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
2bc0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
2bd0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2be0: 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  er is NULL or an
2bf0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a   empty string.**
2c00: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   or a string con
2c10: 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69  taining only whi
2c20: 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d  tespace and comm
2c30: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
2c40: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2c50: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2c60: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2c70: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
2c80: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2c90: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
2ca0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
2cb0: 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20   in terms of.** 
2cc0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2cd0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2ce0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2cf0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d00: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  )]..** The sqlit
2d10: 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e  e3_exec() routin
2d20: 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74  e does nothing t
2d30: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
2d40: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f  hat cannot be do
2d50: 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ne.** by [sqlite
2d60: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2d70: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d80: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2d90: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
2da0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
2db0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2dc0: 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20  e3_exec()] must 
2dd0: 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20  be an valid and 
2de0: 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73  open.** [databas
2df0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
2e00: 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73  *.** The databas
2e10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2e20: 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20  t not be closed 
2e30: 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  while.** [sqlite
2e40: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
2e50: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2e60: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2e70: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
2e80: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
2e90: 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  free.** the memo
2ea0: 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20  ry that *errmsg 
2eb0: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ec0: 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72   at once the err
2ed0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
2ee0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
2ef0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
2f00: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2f10: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2f20: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2f30: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  _exec()].** must
2f40: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2f50: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
2f60: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
2f70: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
2f80: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
2f90: 31 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48  101] [H12102] [H
2fa0: 31 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d 20  12104] [H12105] 
2fb0: 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 30  [H12107] [H12110
2fc0: 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 31  ] [H12113] [H121
2fd0: 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20  16].** [H12119] 
2fe0: 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 35  [H12122] [H12125
2ff0: 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 31  ] [H12131] [H121
3000: 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 31  34] [H12137] [H1
3010: 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2138].*/.int sql
3020: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
3030: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
3040: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3050: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
3060: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
3070: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
3080: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3090: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
30a0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
30b0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
30c0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
30d0: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
30e0: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
30f0: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
3100: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
3110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3120: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
3130: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
3140: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
3150: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
3160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3170: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
3180: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
3190: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
31a0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
31b0: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
31c0: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
31d0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
31e0: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
31f0: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
3200: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
3210: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
3220: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
3230: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
3240: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
3250: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
3260: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
3270: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
3280: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
3290: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
32a0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
32b0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
32c0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
32d0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
32e0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
32f0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
3300: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
3310: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
3320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
3330: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
3340: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
3350: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
3360: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
3370: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
3380: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
3390: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
33a0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
33b0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
33c0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
33d0: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
33e0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
33f0: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
3400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
3410: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
3420: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
3430: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
3440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
3450: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
3460: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
3470: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
3480: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
3490: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
34a0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
34b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
34c0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
34d0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
34e0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
34f0: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
3500: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
3510: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3520: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
3530: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
3540: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
3550: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
3560: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
3570: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
3580: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
3590: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
35a0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
35b0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
35c0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
35d0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
35e0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
35f0: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
3600: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
3610: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
3620: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
3630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3640: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
3650: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3660: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
3670: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
3680: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
3690: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
36a0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
36b0: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
36c0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
36d0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
36e0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
36f0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
3700: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
3710: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
3720: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
3730: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
3740: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
3750: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
3760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
3770: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
3780: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
3790: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
37a0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
37b0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
37c0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
37d0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
37e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
37f0: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
3800: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3810: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
3820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3830: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
3840: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
3850: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
3860: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
3870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
3880: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
3890: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
38a0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
38b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
38c0: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
38d0: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
38e0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
38f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
3900: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
3910: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
3920: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
3930: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
3940: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
3950: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
3960: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
3970: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
3980: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
3990: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
39a0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
39b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
39c0: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
39d0: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
39e0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
39f0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
3a00: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
3a10: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
3a20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3a30: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
3a40: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
3a50: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
3a60: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
3a70: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
3a80: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
3a90: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
3aa0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
3ab0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
3ac0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
3ad0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
3ae0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3af0: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
3b00: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
3b10: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
3b20: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
3b30: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
3b40: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
3b50: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
3b60: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
3b70: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
3b80: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
3b90: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
3ba0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
3bb0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
3bc0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
3bd0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
3be0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
3bf0: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
3c00: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
3c10: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
3c20: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
3c30: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
3c40: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
3c50: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
3c60: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
3c70: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
3c80: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
3c90: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
3ca0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
3cb0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
3cc0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
3cd0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
3ce0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
3cf0: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
3d00: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
3d10: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
3d20: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
3d30: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
3d40: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3d50: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
3d60: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
3d70: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
3d80: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
3d90: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
3da0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
3db0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
3dc0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
3dd0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
3de0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
3df0: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
3e00: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
3e10: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
3e20: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
3e30: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
3e40: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
3e50: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
3e60: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
3e70: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
3e80: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3e90: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
3ea0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
3eb0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
3ec0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3ed0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3ee0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3ef0: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
3f00: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
3f10: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3f20: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
3f30: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
3f40: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
3f50: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
3f60: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
3f70: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
3f80: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
3f90: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
3fa0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
3fb0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
3fc0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
3fd0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
3ff0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4010: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4020: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4030: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4040: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4050: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4060: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4070: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4080: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4090: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
40a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
40b0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
40c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
40d0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
40e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
40f0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4110: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4120: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4130: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4140: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4150: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4160: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4170: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4190: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
41a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
41b0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
41c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
41d0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
41e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
41f0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4210: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4220: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4230: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4240: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4250: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4260: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4270: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4280: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4290: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
42a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
42b0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
42c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
42d0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
42e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
42f0: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4310: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4320: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4330: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4350: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4360: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4370: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4390: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
43a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
43b0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
43c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
43d0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
43e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
43f0: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4410: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
4420: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
4430: 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a 2f  ED | (1<<8) )../
4440: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
4450: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
4460: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
4470: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
4480: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
4490: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
44a0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
44b0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
44c0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
44d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
44e0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
44f0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
4500: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
4510: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
4520: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
4530: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
4540: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4550: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
4560: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
4570: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
4580: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4590: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
45a0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
45b0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
45c0: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
45d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
45e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
45f0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
4600: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4610: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
4620: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4630: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4640: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
4650: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
4660: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
4670: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4680: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
4690: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
46a0: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
46b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
46c0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
46d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
46e0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
46f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4700: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
4710: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4720: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
4730: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4740: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
4750: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
4760: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
4770: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4780: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
4790: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
47a0: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
47b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
47c0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
47d0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
47e0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
47f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4800: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
4810: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
4820: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
4830: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4840: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
4850: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
4860: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
4870: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4880: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
4890: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
48a0: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
48b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
48c0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
48d0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
48e0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
48f0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
4900: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4910: 29 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ) */../*.** CAPI
4920: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
4930: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
4940: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
4950: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4960: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4970: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4980: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4990: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
49a0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
49b0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
49c0: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
49d0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
49e0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
49f0: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
4a00: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
4a10: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
4a20: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
4a30: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
4a40: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
4a50: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
4a60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4a70: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
4a80: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
4a90: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
4aa0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
4ab0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4ac0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
4ad0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
4ae0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
4af0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
4b00: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
4b10: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
4b20: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
4b30: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
4b40: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
4b50: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
4b60: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4b70: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
4b80: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
4b90: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
4ba0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
4bb0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
4bc0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
4bd0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
4be0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
4bf0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
4c00: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
4c10: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
4c20: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
4c30: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
4c40: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
4c50: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
4c60: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
4c70: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
4c80: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
4c90: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
4ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4cb0: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
4cc0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
4cd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4ce0: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
4cf0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
4d00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4d10: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
4d20: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4d30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4d40: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
4d50: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4d60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4d70: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
4d80: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
4d90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4da0: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
4db0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
4dc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4dd0: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
4de0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
4df0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4e00: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
4e10: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
4e20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4e30: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
4e40: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
4e50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
4e60: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
4e70: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
4e80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4e90: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
4ea0: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
4eb0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
4ec0: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
4ed0: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
4ee0: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
4ef0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
4f00: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
4f10: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
4f20: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
4f30: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
4f40: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
4f50: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
4f60: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
4f70: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
4f80: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
4f90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4fa0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
4fb0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
4fc0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
4fd0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
4fe0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
4ff0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
5000: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
5010: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
5020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5030: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
5040: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
5050: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
5060: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
5070: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
5080: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
5090: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
50a0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
50b0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
50c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
50d0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
50e0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
50f0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5100: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5110: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5120: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5130: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5140: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5150: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5160: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5170: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5180: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5190: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
51a0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
51b0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
51c0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
51d0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
51e0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
51f0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
5200: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
5210: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
5220: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
5230: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
5240: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
5250: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
5260: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
5270: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
5280: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
5290: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
52a0: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
52b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
52c0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
52d0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
52e0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
52f0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
5300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
5310: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
5320: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
5330: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
5340: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
5350: 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c  andle {H11110} <
5360: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20110>.**.** An
5370: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
5380: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
5390: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
53a0: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  n the .** [sqlit
53b0: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65  e3_vfs | OS inte
53c0: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49  rface layer].  I
53d0: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
53e0: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d  erface.** implem
53f0: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
5400: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
5410: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
5420: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
5430: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
5440: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
5450: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
5460: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
5470: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
5480: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5490: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
54a0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
54b0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
54c0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
54d0: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
54e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
54f0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
5500: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
5510: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
5520: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
5530: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
5540: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
5550: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
5560: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
5570: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
5580: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
5590: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
55a0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b  Methods Object {
55b0: 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31 30 3e  H11120} <S20110>
55c0: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
55d0: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
55e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f  [sqlite3_vfs] xO
55f0: 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  pen method popul
5600: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
5610: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
5620: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
5630: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
5640: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
5650: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
5660: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
5670: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
5680: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
5690: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
56a0: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
56b0: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
56c0: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
56d0: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
56e0: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
56f0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
5700: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
5710: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
5720: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
5730: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
5740: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
5750: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
5760: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
5770: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
5780: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
5790: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
57a0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
57b0: 65 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65  even if the xOpe
57c0: 6e 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  n reported that 
57d0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
57e0: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
57f0: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
5800: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
5810: 67 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e  g a failed xOpen
5820: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78  .** is for the x
5830: 4f 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20  Open to set the 
5840: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
5850: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f  thods element to
5860: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
5870: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
5880: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
5890: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
58a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
58b0: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
58c0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
58d0: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
58e0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
58f0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
5900: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
5910: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
5920: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
5930: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
5940: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
5950: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
5960: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
5970: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
5980: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
5990: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
59a0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
59b0: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
59c0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
59d0: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
59e0: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
59f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
5a00: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
5a10: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
5a20: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
5a30: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
5a40: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
5a50: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
5a60: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
5a70: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
5a80: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
5a90: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
5aa0: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
5ab0: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
5ac0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
5ad0: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
5ae0: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
5af0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
5b00: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
5b10: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
5b20: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
5b30: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
5b40: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
5b50: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
5b60: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
5b70: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
5b80: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
5b90: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
5ba0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
5bb0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
5bc0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
5bd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
5be0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
5bf0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
5c00: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
5c10: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
5c20: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
5c30: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
5c40: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
5c50: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
5c60: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
5c70: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
5c80: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
5c90: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
5ca0: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
5cb0: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
5cc0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
5cd0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
5ce0: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
5cf0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
5d00: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
5d10: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
5d20: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
5d30: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
5d40: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
5d50: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
5d60: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
5d70: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
5d80: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
5d90: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
5da0: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
5db0: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
5dc0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
5dd0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
5de0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
5df0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
5e00: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
5e10: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
5e20: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
5e30: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
5e40: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
5e50: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
5e60: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
5e70: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
5e80: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
5e90: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
5ea0: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
5eb0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
5ec0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
5ed0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
5ee0: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
5ef0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
5f00: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
5f10: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
5f20: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
5f30: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a  oid conflicts..*
5f40: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
5f50: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
5f60: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
5f70: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
5f80: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
5f90: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
5fa0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
5fb0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
5fc0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
5fd0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
5fe0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
5ff0: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
6000: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
6010: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6020: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
6030: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
6040: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
6050: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
6060: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
6070: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
6080: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6090: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
60a0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
60b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
60c0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
60d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
60e0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
60f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6100: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
6110: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6120: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
6130: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6140: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
6150: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6160: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
6170: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6180: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
6190: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
61a0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
61b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
61c0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
61d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
61e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
61f0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
6200: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6210: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6220: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6230: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6240: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6250: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6260: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
6270: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6280: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6290: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
62a0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
62b0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
62c0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
62d0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
62e0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
62f0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6300: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6310: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6320: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6330: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6340: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6350: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6360: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
6370: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6380: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6390: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
63a0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
63b0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
63c0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
63d0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
63e0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
63f0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6400: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6410: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6420: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6430: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
6440: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
6450: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
6460: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
6470: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
6480: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
6490: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
64a0: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
64b0: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
64c0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
64d0: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
64e0: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
64f0: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
6500: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
6510: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
6520: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
6530: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
6540: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
6550: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
6560: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6570: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6580: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
6590: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
65a0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
65b0: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
65c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
65d0: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
65e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
65f0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
6600: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
6610: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
6620: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
6630: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
6640: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
6650: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
6660: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
6670: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
6680: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
6690: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
66a0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
66b0: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
66c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
66d0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
66e0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
66f0: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
6700: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
6710: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
6720: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
6730: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6740: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
6750: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
6760: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6770: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
6780: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
6790: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
67a0: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
67b0: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
67c0: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
67d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
67e0: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
67f0: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
6800: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
6810: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
6820: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
6830: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
6840: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
6850: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
6860: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
6870: 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 48 31 31  rol Opcodes {H11
6880: 33 31 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a  310} <S30800>.**
6890: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
68a0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
68b0: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
68c0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
68d0: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
68e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
68f0: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
6900: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
6910: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
6920: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
6930: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
6940: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
6950: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
6960: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
6970: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
6980: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
6990: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
69a0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
69b0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
69c0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
69d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
69e0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
69f0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
6a00: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6a10: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
6a20: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
6a30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6a40: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
6a50: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
6a60: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
6a70: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
6a80: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
6a90: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
6aa0: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
6ab0: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
6ac0: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
6ad0: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
6ae0: 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ned..*/.#define 
6af0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6b00: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a  KSTATE        1.
6b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
6b20: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
6b30: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6b40: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
6b50: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a  ROXYFILE      3.
6b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6b70: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
6b80: 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43        4../*.** C
6b90: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
6ba0: 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c  andle {H17110} <
6bb0: 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20130>.**.** Th
6bc0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
6bd0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
6be0: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
6bf0: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
6c00: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
6c10: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
6c20: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
6c30: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
6c40: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
6c50: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
6c60: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
6c70: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
6c80: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
6c90: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
6ca0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
6cb0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
6cc0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
6cd0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
6ce0: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
6cf0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
6d00: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
6d10: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
6d20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6d30: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
6d40: 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53  ject {H11140} <S
6d50: 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20  20100>.**.** An 
6d60: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
6d70: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
6d80: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
6d90: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
6da0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
6db0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
6dc0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
6dd0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
6de0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
6df0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
6e00: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
6e10: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
6e20: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
6e30: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
6e40: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
6e50: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
6e60: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
6e70: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
6e80: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
6e90: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
6ea0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
6eb0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
6ec0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
6ed0: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
6ee0: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
6ef0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
6f00: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
6f10: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
6f20: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
6f30: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
6f40: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
6f50: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
6f60: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
6f70: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
6f80: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
6f90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
6fa0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
6fb0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
6fc0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
6fd0: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
6fe0: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
6ff0: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
7000: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
7010: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
7020: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
7030: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
7040: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
7050: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
7060: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
7070: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
7080: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
7090: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
70a0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
70b0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
70c0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
70d0: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
70e0: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
70f0: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
7100: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
7110: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
7120: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
7130: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
7140: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
7150: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
7160: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
7170: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7180: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
7190: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
71a0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
71b0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
71c0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
71d0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
71e0: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
71f0: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
7200: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
7210: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
7220: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
7230: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
7240: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
7250: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
7260: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
7270: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
7280: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
7290: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
72a0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
72b0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
72c0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
72d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
72e0: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
72f0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
7300: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
7310: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
7320: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
7330: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
7340: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
7350: 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  l guarantee that
7360: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
7370: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
7380: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
7390: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
73a0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
73b0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
73c0: 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74  thname().  SQLit
73d0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
73e0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
73f0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
7400: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
7410: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
7420: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
7430: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
7440: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
7450: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
7460: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
7470: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
7480: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
7490: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
74a0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
74b0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
74c0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
74d0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
74e0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f   parameter is xO
74f0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
7500: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
7510: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
7520: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
7530: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
7540: 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74  ile.  Whenever t
7550: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
7560: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
7570: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
7580: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
7590: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
75a0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
75b0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
75c0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
75d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
75e0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
75f0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
7600: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
7610: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
7620: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
7630: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
7640: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
7650: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
7660: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
7670: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
7680: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
7690: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
76a0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
76b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
76c0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
76d0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
76e0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
76f0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
7700: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
7710: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
7720: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
7730: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
7740: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
7750: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
7760: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
7770: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
7780: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
7790: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
77a0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
77b0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
77c0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
77d0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
77e0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
77f0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7800: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
7810: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7820: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
7830: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7840: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
7850: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
7860: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
7870: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
7880: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7890: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
78a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
78b0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
78c0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
78d0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
78e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
78f0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
7900: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
7910: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
7920: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
7930: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
7940: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
7950: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
7960: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
7970: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
7980: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
7990: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
79a0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
79b0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
79c0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
79d0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
79e0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
79f0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
7a00: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
7a10: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
7a20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
7a30: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
7a40: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
7a50: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
7a60: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
7a70: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
7a80: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
7a90: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
7aa0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
7ab0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
7ac0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
7ad0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
7ae0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
7af0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
7b00: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
7b10: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
7b20: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
7b30: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7b40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
7b50: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
7b60: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
7b70: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
7b80: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
7b90: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
7ba0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
7bb0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
7bc0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
7bd0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
7be0: 73 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  sed.  The [SQLIT
7bf0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7c00: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
7c10: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64   set for TEMP  d
7c20: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61  atabases, journa
7c30: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f  ls and for subjo
7c40: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  urnals..**.** Th
7c50: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
7c60: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
7c70: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
7c80: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
7c90: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
7ca0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
7cb0: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
7cc0: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
7cd0: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
7ce0: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
7cf0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
7d00: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
7d10: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
7d20: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
7d30: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
7d40: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
7d50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7d60: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
7d70: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
7d80: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
7d90: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
7da0: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
7db0: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
7dc0: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
7dd0: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
7de0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
7df0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7e00: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
7e10: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
7e20: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65  ess..**.** At le
7e30: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
7e40: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
7e50: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
7e60: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
7e70: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
7e80: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
7e90: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
7ea0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
7eb0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
7ec0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
7ed0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
7ee0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
7ef0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
7f00: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
7f10: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
7f20: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
7f30: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
7f40: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7f50: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
7f60: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
7f70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7f80: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
7f90: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
7fa0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
7fb0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
7fc0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
7fd0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
7fe0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
7ff0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
8000: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
8010: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
8020: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
8030: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
8040: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
8050: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  call..**.** The 
8060: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8070: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
8080: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
8090: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
80a0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
80b0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
80c0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
80d0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
80e0: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
80f0: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
8100: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
8110: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
8120: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
8130: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
8140: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
8150: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
8160: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
8170: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
8180: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  ** SQLite will a
8190: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
81a0: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
81b0: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
81c0: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
81d0: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
81e0: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
81f0: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
8200: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
8210: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
8220: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
8230: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
8240: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
8250: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
8260: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
8270: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
8280: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
8290: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
82a0: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
82b0: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
82c0: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
82d0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
82e0: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
82f0: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
8300: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
8310: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
8320: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
8330: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
8340: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
8350: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
8360: 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  me() interfaces.
8370: 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  ** are not stric
8380: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
8390: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
83a0: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
83b0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
83c0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
83d0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
83e0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
83f0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
8400: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
8410: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
8420: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
8430: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
8440: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
8450: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
8460: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
8470: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
8480: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
8490: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
84a0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
84b0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
84c0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
84d0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
84e0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
84f0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65  onds given.  The
8500: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
8510: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
8520: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
8530: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
8540: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
8550: 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64  ime..**.*/.typed
8560: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
8570: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
8580: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
8590: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
85a0: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
85b0: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
85c0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a  version number *
85d0: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
85e0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
85f0: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
8600: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
8610: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
8620: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
8630: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
8640: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
8650: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
8660: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
8670: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
8680: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
8690: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
86a0: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
86b0: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
86c0: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
86d0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
86e0: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
86f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
8700: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
8710: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
8720: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8730: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
8740: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
8750: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
8760: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
8770: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
8780: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
8790: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
87a0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
87b0: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
87c0: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
87d0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
87e0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
87f0: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
8800: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
8810: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
8820: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
8830: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
8840: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
8850: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
8860: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
8870: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
8880: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
8890: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
88a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
88b0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
88c0: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
88d0: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
88e0: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
88f0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
8900: 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
8910: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
8920: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
8930: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
8940: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
8950: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
8960: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
8970: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
8980: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8990: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
89a0: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
89b0: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
89c0: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
89d0: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
89e0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
89f0: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
8a00: 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64  ;.  /* New field
8a10: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
8a20: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
8a30: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
8a40: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
8a50: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
8a60: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
8a70: 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ens. */.};../*.*
8a80: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
8a90: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
8aa0: 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31  s VFS method {H1
8ab0: 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a  1190} <H11140>.*
8ac0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8ad0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
8ae0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
8af0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
8b00: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
8b10: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
8b20: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
8b30: 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79  ect. {END}  They
8b40: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
8b50: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
8b60: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
8b70: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
8b80: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
8b90: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
8ba0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
8bb0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
8bc0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
8bd0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
8be0: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
8bf0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
8c00: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
8c10: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
8c20: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
8c30: 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64  ile is both read
8c40: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
8c50: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
8c60: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
8c70: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
8c80: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
8c90: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
8ca0: 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65  readable..*/.#de
8cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
8cc0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
8cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
8ce0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
8cf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8d00: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
8d10: 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   2../*.** CAPI3R
8d20: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
8d30: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
8d40: 79 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30  y {H10130} <S200
8d50: 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a  00><S30100>.**.*
8d60: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
8d70: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
8d80: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
8d90: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
8da0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
8db0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
8dc0: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
8dd0: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
8de0: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
8df0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
8e00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
8e10: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
8e20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8e30: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
8e40: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
8e50: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
8e60: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
8e70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
8e80: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
8e90: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
8ea0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
8eb0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
8ec0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
8ed0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
8ee0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
8ef0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
8f00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
8f10: 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66  ().  Only an eff
8f20: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
8f30: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
8f40: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
8f50: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
8f60: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
8f70: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
8f80: 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41   no-ops..**.** A
8f90: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
8fa0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
8fb0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
8fc0: 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
8fd0: 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
8fe0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
8ff0: 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
9000: 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
9010: 61 6c 69 7a 65 28 29 2e 20 20 4f 6e 6c 79 0a 2a  alize().  Only.*
9020: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
9030: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
9040: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
9050: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
9060: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
9070: 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  r calls to sqlit
9080: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
9090: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
90a0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  s..**.** Among o
90b0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c  ther things, sql
90c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
90d0: 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  ) shall invoke.*
90e0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
90f0: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
9100: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9110: 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76  n().** shall inv
9120: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
9130: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nd()..**.** The 
9140: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9150: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
9160: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
9170: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
9180: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
9190: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
91a0: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
91b0: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
91c0: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
91d0: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
91e0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
91f0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
9200: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
9210: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
9220: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
9230: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
9240: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
9250: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9260: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
9270: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
9280: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
9290: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
92a0: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
92b0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
92c0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
92d0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
92e0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
92f0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
9300: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
9310: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
9320: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
9330: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9340: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
9350: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
9360: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
9370: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
9380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
9390: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
93a0: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
93b0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
93c0: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  dy.  However, if
93d0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
93e0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
93f0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
9400: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
9410: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
9420: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
9430: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
9440: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
9450: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
9460: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
9470: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
9480: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
9490: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
94a0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
94b0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
94c0: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
94d0: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
94e0: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
94f0: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
9500: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
9510: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
9520: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
9530: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
9540: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
9550: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
9560: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
9570: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
9580: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
9590: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
95a0: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
95b0: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
95c0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
95d0: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
95e0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
95f0: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
9600: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
9610: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
9620: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
9630: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
9640: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9650: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
9660: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
9670: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
9680: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
9690: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
96a0: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
96b0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
96c0: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
96d0: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
96e0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
96f0: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
9700: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
9710: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
9720: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
9730: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
9740: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
9750: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
9760: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
9770: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
9780: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
9790: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
97a0: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
97b0: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
97c0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
97d0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
97e0: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
97f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
9800: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
9810: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
9820: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
9830: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
9840: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
9850: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
9860: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
9870: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
9880: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
9890: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
98a0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
98b0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
98c0: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
98d0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
98e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
98f0: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
9900: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
9910: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
9920: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
9930: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
9940: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
9950: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
9960: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
9970: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
9980: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
9990: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
99a0: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
99b0: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
99c0: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
99d0: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
99e0: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
99f0: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
9a00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
9a10: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
9a20: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
9a30: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
9a40: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
9a50: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
9a60: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
9a70: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
9a80: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
9a90: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
9aa0: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
9ab0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
9ac0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
9ad0: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
9ae0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
9af0: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
9b00: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
9b10: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
9b20: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
9b30: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
9b40: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
9b50: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
9b60: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
9b70: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
9b80: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
9b90: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9ba0: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
9bb0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9bc0: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
9bd0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
9be0: 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e  H14100} <S20000>
9bf0: 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <S30200>.** EXPE
9c00: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
9c10: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
9c20: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
9c30: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
9c40: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
9c50: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
9c60: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
9c70: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
9c80: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
9c90: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
9ca0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
9cb0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
9cc0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
9cd0: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
9ce0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
9cf0: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
9d00: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
9d10: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
9d20: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
9d30: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
9d40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
9d50: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
9d60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9d70: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
9d80: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
9d90: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
9da0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
9db0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
9dc0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
9dd0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
9de0: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
9df0: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
9e00: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9e10: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
9e20: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
9e30: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
9e40: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
9e50: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
9e60: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
9e70: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
9e80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9e90: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
9ea0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
9eb0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
9ec0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
9ed0: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  that sqlite3_con
9ee0: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
9ef0: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
9f00: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
9f10: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
9f20: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
9f30: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9f40: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
9f50: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
9f60: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9f70: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
9f80: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
9f90: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
9fa0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
9fb0: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
9fc0: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
9fd0: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
9fe0: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
9ff0: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
a000: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
a010: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
a020: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
a030: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
a040: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
a050: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
a060: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
a070: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20  t..**.** When a 
a080: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a090: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
a0a0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
a0b0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
a0c0: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74  ]..** If the opt
a0d0: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
a0e0: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
a0f0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
a100: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
a110: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
a120: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
a130: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
a140: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
a150: 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 31 34 31  * [H14103] [H141
a160: 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b 48 31  06] [H14120] [H1
a170: 34 31 32 33 5d 20 5b 48 31 34 31 32 36 5d 20 5b  4123] [H14126] [
a180: 48 31 34 31 32 39 5d 20 5b 48 31 34 31 33 32 5d  H14129] [H14132]
a190: 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 48 31   [H14135].** [H1
a1a0: 34 31 33 38 5d 20 5b 48 31 34 31 34 31 5d 20 5b  4138] [H14141] [
a1b0: 48 31 34 31 34 34 5d 20 5b 48 31 34 31 34 37 5d  H14144] [H14147]
a1c0: 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 34 31 35   [H14150] [H1415
a1d0: 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48 31 34  3] [H14156] [H14
a1e0: 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 32 5d  159].** [H14162]
a1f0: 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 34 31 36   [H14165] [H1416
a200: 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  8].*/.SQLITE_EXP
a210: 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
a220: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
a230: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
a240: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
a250: 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
a260: 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32 30 30  ections  {H14200
a270: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
a280: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
a290: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
a2a0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
a2b0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
a2c0: 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
a2d0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
a2e0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
a2f0: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
a300: 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
a310: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a320: 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
a330: 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
a340: 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
a350: 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
a360: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
a370: 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
a380: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
a390: 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
a3a0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
a3b0: 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20  erface can only 
a3c0: 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74  be used immediat
a3d0: 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65  ely after.** the
a3e0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a3f0: 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20  tion is created 
a400: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
a410: 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  pen()],.** [sqli
a420: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
a430: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
a440: 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  v2()].  .**.** T
a450: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
a460: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
a470: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
a480: 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66    is the.** conf
a490: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d  iguration verb -
a4a0: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
a4b0: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
a4c0: 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f  what.** aspect o
a4d0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
a4e0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
a4f0: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
a500: 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f  .** The only cho
a510: 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c  ice for this val
a520: 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42  ue is [SQLITE_DB
a530: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
a540: 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20  ]..** New verbs 
a550: 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65  are likely to be
a560: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
a570: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
a580: 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  ite..** Addition
a590: 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70  al arguments dep
a5a0: 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e  end on the verb.
a5b0: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
a5c0: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d  nts:.** [H14203]
a5d0: 20 5b 48 31 34 32 30 36 5d 20 5b 48 31 34 32 30   [H14206] [H1420
a5e0: 39 5d 20 5b 48 31 34 32 31 32 5d 20 5b 48 31 34  9] [H14212] [H14
a5f0: 32 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  215].*/.SQLITE_E
a600: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
a610: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
a620: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
a630: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
a640: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
a650: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
a660: 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c  tines {H10155} <
a670: 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52  S20120>.** EXPER
a680: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e  IMENTAL.**.** An
a690: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
a6a0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
a6b0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
a6c0: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
a6d0: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
a6e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
a6f0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
a700: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
a710: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
a720: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
a730: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
a740: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
a750: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
a760: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
a770: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
a780: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
a790: 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
a7a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
a7b0: 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
a7c0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
a7d0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
a7e0: 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
a7f0: 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
a800: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
a810: 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
a820: 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
a830: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
a840: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
a850: 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
a860: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
a870: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
a880: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
a890: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
a8a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
a8b0: 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
a8c0: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
a8d0: 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
a8e0: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
a8f0: 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
a900: 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
a910: 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
a920: 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
a930: 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
a940: 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
a950: 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
a960: 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
a970: 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
a980: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
a990: 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
a9a0: 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
a9b0: 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
a9c0: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
a9d0: 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
a9e0: 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
a9f0: 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
aa00: 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
aa10: 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
aa20: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
aa30: 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
aa40: 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
aa50: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
aa60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
aa70: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
aa80: 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
aa90: 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
aaa0: 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
aab0: 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
aac0: 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
aad0: 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
aae0: 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
aaf0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
ab00: 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  c and xFree meth
ab10: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
ab20: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
ab30: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
ab40: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
ab50: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
ab60: 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61  ary..** The xRea
ab70: 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74  lloc method must
ab80: 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c   work like reall
ab90: 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74  oc() from the st
aba0: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
abb0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63  .** with the exc
abc0: 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74  eption that if t
abd0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
abe0: 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69  nt to xRealloc i
abf0: 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c  s zero,.** xReal
ac00: 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f  loc must be a no
ac10: 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f  -op - it must no
ac20: 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c  t perform any al
ac30: 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64  location or.** d
ac40: 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 53 51  eallocation.  SQ
ac50: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 64 73  Lite guaranteeds
ac60: 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
ac70: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
ac80: 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
ac90: 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
aca0: 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
acb0: 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
acc0: 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61  .** And so in ca
acd0: 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64  ses where xRound
ace0: 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  up always return
acf0: 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d  s a positive num
ad00: 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  ber,.** xRealloc
ad10: 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61   can perform exa
ad20: 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e  ctly as the stan
ad30: 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61  dard library rea
ad40: 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74  lloc() and.** st
ad50: 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69  ill be in compli
ad60: 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73  ance with this s
ad70: 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a  pecification..**
ad80: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
ad90: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
ada0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
adb0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
adc0: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
add0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
ade0: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
adf0: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
ae00: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
ae10: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
ae20: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
ae30: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
ae40: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
ae50: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
ae60: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
ae70: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
ae80: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
ae90: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
aea0: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
aeb0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
aec0: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
aed0: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
aee0: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
aef0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
af00: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
af10: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
af20: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
af30: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
af40: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
af50: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
af60: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
af70: 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
af80: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
af90: 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
afa0: 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
afb0: 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
afc0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
afd0: 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
afe0: 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
aff0: 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
b000: 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
b010: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
b020: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b030: 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
b040: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
b050: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
b060: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
b070: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
b080: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
b090: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
b0a0: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
b0b0: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
b0c0: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
b0d0: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
b0e0: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
b0f0: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
b100: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
b110: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
b120: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
b130: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
b140: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
b150: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
b160: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
b170: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
b180: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
b190: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
b1a0: 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
b1b0: 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
b1c0: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
b1d0: 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
b1e0: 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
b1f0: 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
b200: 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
b210: 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
b220: 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
b230: 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
b240: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
b250: 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
b260: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
b270: 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
b280: 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
b290: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
b2a0: 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
b2b0: 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
b2c0: 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
b2d0: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
b2e0: 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
b2f0: 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
b300: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
b310: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
b320: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b330: 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
b340: 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
b350: 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
b360: 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
b370: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
b380: 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
b390: 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
b3a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
b3b0: 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
b3c0: 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
b3d0: 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
b3e0: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
b3f0: 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
b400: 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
b410: 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
b420: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
b430: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
b440: 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
b450: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
b460: 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
b470: 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
b480: 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
b490: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
b4a0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b4b0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
b4c0: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
b4d0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b4e0: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
b4f0: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
b500: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
b510: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
b520: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
b530: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
b540: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
b550: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
b560: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
b570: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
b580: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
b590: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
b5a0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
b5b0: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
b5c0: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
b5d0: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
b5e0: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
b5f0: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
b600: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
b610: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
b620: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
b630: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
b640: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
b650: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
b660: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
b670: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
b680: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
b690: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
b6a0: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
b6b0: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
b6c0: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
b6d0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
b6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
b6f0: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
b700: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
b710: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
b720: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
b730: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
b740: 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30   {H10160} <S2000
b750: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
b760: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  AL.**.** These c
b770: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
b780: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
b790: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
b7a0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
b7b0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
b7c0: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
b7d0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
b7e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
b7f0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
b800: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
b810: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
b820: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
b830: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
b840: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
b850: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
b860: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
b870: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
b880: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
b890: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
b8a0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
b8b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
b8c0: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
b8d0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
b8e0: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
b8f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b900: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
b910: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
b920: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
b930: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
b940: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
b950: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
b960: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
b970: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
b980: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
b990: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
b9a0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
b9b0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
b9c0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
b9d0: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
b9e0: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a  tion disables.**
b9f0: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
ba00: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
ba10: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
ba20: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
ba30: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
ba40: 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a  le thread.</dd>.
ba50: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
ba60: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
ba70: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
ba80: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
ba90: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
baa0: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74  ption.  This opt
bab0: 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20  ion disables.** 
bac0: 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
bad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bae0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
baf0: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
bb00: 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
bb10: 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
bb20: 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
bb30: 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
bb40: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
bb50: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
bb60: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
bb70: 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
bb80: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
bb90: 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
bba0: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
bbb0: 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
bbc0: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
bbd0: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
bbe0: 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
bbf0: 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
bc00: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
bc10: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
bc20: 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
bc30: 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74  ame time.  See t
bc40: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
bc50: 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61  de].** documenta
bc60: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
bc70: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
bc80: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bc90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
bca0: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
bcb0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
bcc0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
bcd0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
bce0: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
bcf0: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
bd00: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
bd10: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
bd20: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
bd30: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
bd40: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
bd50: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
bd60: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
bd70: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
bd80: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
bd90: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
bda0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
bdb0: 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
bdc0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
bdd0: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
bde0: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
bdf0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
be00: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
be10: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
be20: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
be30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
be40: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
be50: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
be60: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
be70: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
be80: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
be90: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
bea0: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
beb0: 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65  time..** See the
bec0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
bed0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
bee0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
bef0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e  nformation.</dd>
bf00: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
bf10: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
bf20: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
bf30: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
bf40: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
bf50: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
bf60: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
bf70: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
bf80: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
bf90: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
bfa0: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
bfb0: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
bfc0: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
bfd0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bfe0: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
bff0: 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
c000: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
c010: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
c020: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
c030: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ite.</dd>.**.** 
c040: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c050: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
c060: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c070: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
c080: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
c090: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
c0a0: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
c0b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
c0c0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
c0d0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
c0e0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c0f0: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
c100: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
c110: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
c120: 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
c130: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c140: 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ..** This option
c150: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
c160: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
c170: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
c180: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
c190: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
c1a0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
c1b0: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
c1c0: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
c1d0: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
c1e0: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
c1f0: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ple.</dd>.**.** 
c200: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c210: 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
c220: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c230: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
c240: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
c250: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
c260: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
c270: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
c280: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
c290: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
c2a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c2b0: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
c2c0: 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64  s. When disabled
c2d0: 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
c2e0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c2f0: 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e  s become .** non
c300: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
c310: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
c320: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
c330: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
c340: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
c350: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
c360: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c370: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
c380: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  mit()].**   <li>
c390: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
c3a0: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a  ()].**   </ul>.*
c3b0: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
c3c0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c3d0: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
c3e0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c3f0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c400: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c410: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
c420: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
c430: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
c440: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
c450: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
c460: 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
c470: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
c480: 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
c490: 20 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f   the scrach allo
c4a0: 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
c4b0: 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
c4c0: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
c4d0: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
c4e0: 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
c4f0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
c500: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
c510: 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
c520: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
c530: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
c540: 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70   of 16. The sz p
c550: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
c560: 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a  be a few bytes.*
c570: 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  * larger than th
c580: 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68  e actual scratch
c590: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
c5a0: 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20  due to internal 
c5b0: 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65  overhead..** The
c5c0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
c5d0: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74  should pointer t
c5e0: 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  o an 8-byte alig
c5f0: 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66  ned buffer.** of
c600: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
c610: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
c620: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  ** SQLite will u
c630: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
c640: 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
c650: 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74  er at once per t
c660: 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73  hread, so.** N s
c670: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
c680: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
c690: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
c6a0: 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a  hreads.  The sz.
c6b0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  ** parameter sho
c6c0: 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74  uld be 6 times t
c6d0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
c6e0: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
c6f0: 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63  page size..** Sc
c700: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72  ratch buffers ar
c710: 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f  e used as part o
c720: 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61  f the btree bala
c730: 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  nce operation.  
c740: 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20  If.** The btree 
c750: 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61  balancer needs a
c760: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79  dditional memory
c770: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
c780: 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73  provided by.** s
c790: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f  cratch buffers o
c7a0: 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20  r if no scratch 
c7b0: 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20  buffer space is 
c7c0: 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
c7d0: 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74  SQLite.** goes t
c7e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
c7f0: 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74  c()] to obtain t
c800: 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65  he memory it nee
c810: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ds.</dd>.**.** <
c820: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c830: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
c840: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c850: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
c860: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
c870: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
c880: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
c890: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
c8a0: 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
c8b0: 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
c8c0: 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e  he implemenation
c8d0: 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
c8e0: 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
c8f0: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
c900: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
c910: 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
c920: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
c930: 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
c940: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
c950: 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69  NFIG_PCACHE opti
c960: 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
c970: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
c980: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
c990: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
c9a0: 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
c9b0: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
c9c0: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
c9d0: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
c9e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
c9f0: 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
ca00: 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
ca10: 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
ca20: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
ca30: 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
ca40: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
ca50: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
ca60: 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
ca70: 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
ca80: 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
ca90: 2e 20 20 54 68 65 20 70 61 67 65 20 68 65 61 64  .  The page head
caa0: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
cab0: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
cac0: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
cad0: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
cae0: 20 20 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73    It is harmless
caf0: 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
cb00: 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
cb10: 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
cb20: 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
cb30: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
cb40: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
cb50: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
cb60: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
cb70: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
cb80: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69   memory..** SQLi
cb90: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
cba0: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
cbb0: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
cbc0: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
cbd0: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
cbe0: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
cbf0: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
cc00: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
cc10: 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  .  If additional
cc20: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
cc30: 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
cc40: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
cc50: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
cc60: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
cc70: 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
cc80: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
cc90: 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
cca0: 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
ccb0: 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  ce..** The imple
ccc0: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
ccd0: 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  use one or more 
cce0: 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73  of the N buffers
ccf0: 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d   to hold .** mem
cd00: 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
cd10: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20  nformation. The 
cd20: 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
cd30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
cd40: 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
cd50: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
cd60: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
cd70: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
cd80: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
cd90: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
cda0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cdb0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
cdc0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
cdd0: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
cde0: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
cdf0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
ce00: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
ce10: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
ce20: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
ce30: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
ce40: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
ce50: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
ce60: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
ce70: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
ce80: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
ce90: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
cea0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
ceb0: 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
cec0: 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
ced0: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
cee0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
cef0: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
cf00: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
cf10: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
cf20: 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 49  ation size..** I
cf30: 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
cf40: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
cf50: 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
cf60: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
cf70: 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
cf80: 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
cf90: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
cfa0: 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
cfb0: 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
cfc0: 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
cfd0: 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
cfe0: 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
cff0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
d000: 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72   If the.** memor
d010: 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
d020: 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
d030: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
d040: 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
d050: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
d060: 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
d070: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
d080: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
d090: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
d0a0: 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
d0b0: 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
d0c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d0d0: 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
d0e0: 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
d0f0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
d100: 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
d110: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
d120: 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
d130: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
d140: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
d150: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
d160: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d170: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
d180: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
d190: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d1a0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
d1b0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
d1c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
d1d0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d1e0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
d1f0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
d200: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
d210: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
d220: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
d230: 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
d240: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
d250: 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75   place.** the mu
d260: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
d270: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c  lt into SQLite.<
d280: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d290: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d2a0: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
d2b0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
d2c0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
d2d0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
d2e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
d2f0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
d300: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
d310: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
d320: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
d330: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
d340: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
d350: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
d360: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
d370: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
d380: 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f  tines..** This o
d390: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
d3a0: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
d3b0: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
d3c0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
d3d0: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
d3e0: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
d3f0: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
d400: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
d410: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
d420: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
d430: 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  mple.</dd>.**.**
d440: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d450: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
d460: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
d470: 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
d480: 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
d490: 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
d4a0: 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
d4b0: 6c 6f 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69  location lookasi
d4c0: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  de optimization.
d4d0: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
d4e0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
d4f0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
d500: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
d510: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
d520: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
d530: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
d540: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
d550: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d560: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  .  This option s
d570: 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
d580: 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
d590: 69 64 65 20 73 69 7a 65 2e 20 20 54 68 65 20 5b  ide size.  The [
d5a0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
d5b0: 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
d5c0: 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
d5d0: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
d5e0: 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
d5f0: 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
d600: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
d610: 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
d620: 6f 6e 6e 65 63 74 69 6f 6e 73 2e 3c 2f 64 64 3e  onnections.</dd>
d630: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
d640: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c  E_CONFIG_PCACHE<
d650: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
d660: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
d670: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
d680: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
d690: 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c  er to.** an [sql
d6a0: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
d6b0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ods] object.  Th
d6c0: 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
d6d0: 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
d6e0: 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
d6f0: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
d700: 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c  ementation.  SQL
d710: 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
d720: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
d730: 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
d740: 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
d750: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
d760: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d770: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d780: 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  TPCACHE</dt>.** 
d790: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
d7a0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
d7b0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
d7c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
d7d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
d7e0: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
d7f0: 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
d800: 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
d810: 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
d820: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d830: 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
d840: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64  .</dd>.**.** </d
d850: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
d860: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
d870: 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
d880: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
d890: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
d8a0: 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
d8b0: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
d8c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
d8d0: 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
d8e0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
d8f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
d900: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
d910: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
d920: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
d930: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
d940: 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
d950: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
d960: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
d970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d980: 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
d990: 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
d9a0: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
d9b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d9c0: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
d9d0: 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
d9e0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
d9f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
da00: 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
da10: 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
da20: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
da30: 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
da40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
da50: 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
da60: 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
da70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
da80: 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
da90: 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
daa0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
dab0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dac0: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
dad0: 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
dae0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
daf0: 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
db00: 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
db10: 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
db20: 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
db30: 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
db40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
db50: 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
db60: 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
db70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
db80: 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
db90: 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  14  /* sqlite3_p
dba0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
dbb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dbc0: 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
dbd0: 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69  E    15  /* sqli
dbe0: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
dbf0: 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ds* */../*.** CA
dc00: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
dc10: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48  ation Options {H
dc20: 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10170} <S20000>.
dc30: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
dc40: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
dc50: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
dc60: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
dc70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
dc80: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
dc90: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
dca0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
dcb0: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
dcc0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
dcd0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
dce0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
dcf0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
dd00: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
dd10: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
dd20: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
dd30: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
dd40: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
dd50: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
dd60: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
dd70: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
dd80: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
dd90: 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
dda0: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
ddb0: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
ddc0: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
ddd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
dde0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
ddf0: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
de00: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
de10: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
de20: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
de30: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
de40: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
de50: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
de60: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
de70: 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
de80: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
de90: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
dea0: 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
deb0: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
dec0: 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
ded0: 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
dee0: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
def0: 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
df00: 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
df10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
df20: 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
df30: 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
df40: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
df50: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
df60: 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
df70: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d   pointer to an m
df80: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
df90: 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
dfa0: 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 54 68 65  e memory..** The
dfb0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
dfc0: 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
dfd0: 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
dfe0: 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
dff0: 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
e000: 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
e010: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
e020: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63  loc()].  The sec
e030: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
e040: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
e050: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
e060: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
e070: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
e080: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
e090: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
e0a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
e0b0: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
e0c0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
e0d0: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
e0e0: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
e0f0: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
e100: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
e110: 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
e120: 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
e130: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
e140: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
e150: 79 2e 20 20 49 66 20 74 68 65 20 73 65 63 6f 6e  y.  If the secon
e160: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 6f  d argument is no
e170: 74 0a 2a 2a 20 61 20 6d 75 6c 74 69 70 6c 65 20  t.** a multiple 
e180: 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
e190: 72 6e 61 6c 6c 79 20 72 6f 75 6e 64 65 64 20 64  rnally rounded d
e1a0: 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
e1b0: 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69  smaller.** multi
e1c0: 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20 61  ple of 8.  See a
e1d0: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  lso: [SQLITE_CON
e1e0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f  FIG_LOOKASIDE]</
e1f0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
e200: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e210: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
e220: 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a  SIDE    1001  /*
e230: 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
e240: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
e250: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
e260: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
e270: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32  esult Codes {H12
e280: 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  200} <S10700>.**
e290: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e2a0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
e2b0: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
e2c0: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
e2d0: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
e2e0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
e2f0: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
e300: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64  Lite. The extend
e310: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
e320: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
e330: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
e340: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
e350: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72  ibility consider
e360: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  ations..**.** Re
e370: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
e380: 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 5d  H12201] [H12202]
e390: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
e3a0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
e3b0: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
e3c0: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
e3d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
e3e0: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b  t Insert Rowid {
e3f0: 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e  H12220} <S10700>
e400: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72  .**.** Each entr
e410: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
e420: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
e430: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
e440: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
e450: 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
e460: 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65   | "rowid"]. The
e470: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
e480: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
e490: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
e4a0: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
e4b0: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
e4c0: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
e4d0: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
e4e0: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
e4f0: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
e500: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49  lared columns. I
e510: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
e520: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
e530: 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
e540: 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
e550: 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
e560: 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
e570: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
e580: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
e590: 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
e5a0: 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
e5b0: 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
e5c0: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
e5d0: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
e5e0: 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
e5f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
e600: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
e610: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f  argument.  If no
e620: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
e630: 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
e640: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
e650: 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
e660: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
e670: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
e680: 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20   If an [INSERT] 
e690: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
e6a0: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
e6b0: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
e6c0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
e6d0: 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
e6e0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20  this routine as 
e6f0: 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
e700: 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ger is running..
e710: 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
e720: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
e730: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
e740: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
e750: 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74  outine.** revert
e760: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
e770: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
e780: 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
e790: 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  fired..**.** An 
e7a0: 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
e7b0: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
e7c0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
e7d0: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
e7e0: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
e7f0: 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
e800: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
e810: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
e820: 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  .** routine.  Th
e830: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
e840: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
e850: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
e860: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
e870: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
e880: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
e890: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
e8a0: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
e8b0: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
e8c0: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
e8d0: 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20  s.  When INSERT 
e8e0: 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
e8f0: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
e900: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
e910: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
e920: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
e930: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
e940: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
e950: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
e960: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
e970: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
e980: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
e990: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
e9a0: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
e9b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
e9c0: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
e9d0: 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  e..**.** For the
e9e0: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
e9f0: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
ea00: 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
ea10: 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
ea20: 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
ea30: 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
ea40: 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
ea50: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
ea60: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d  nts:.** [H12221]
ea70: 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20   [H12223].**.** 
ea80: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
ea90: 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
eaa0: 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
eab0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
eac0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
ead0: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
eae0: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
eaf0: 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
eb00: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
eb10: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
eb20: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
eb30: 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
eb40: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
eb50: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
eb60: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
eb70: 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
eb80: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
eb90: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
eba0: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
ebb0: 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
ebc0: 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
ebd0: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
ebe0: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
ebf0: 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
ec00: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
ec10: 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
ec20: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
ec30: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d  odified {H12240}
ec40: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
ec50: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
ec60: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
ec70: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
ec80: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
ec90: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
eca0: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
ecb0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
ecc0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
ecd0: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
ece0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
ecf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
ed00: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
ed10: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
ed20: 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
ed30: 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
ed40: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
ed50: 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
ed60: 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
ed70: 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
ed80: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
ed90: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
eda0: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
edb0: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
edc0: 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
edd0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
ede0: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
edf0: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
ee00: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
ee10: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
ee20: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
ee30: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
ee40: 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
ee50: 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
ee60: 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
ee70: 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
ee80: 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
ee90: 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
eea0: 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
eeb0: 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
eec0: 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
eed0: 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
eee0: 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
eef0: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
ef00: 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
ef10: 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
ef20: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
ef30: 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
ef40: 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
ef50: 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
ef60: 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
ef70: 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
ef80: 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
ef90: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
efa0: 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
efb0: 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
efc0: 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
efd0: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
efe0: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
eff0: 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
f000: 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
f010: 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
f020: 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
f030: 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
f040: 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
f050: 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
f060: 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
f070: 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
f080: 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
f090: 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
f0a0: 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
f0b0: 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
f0c0: 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
f0d0: 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
f0e0: 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
f0f0: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
f100: 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
f110: 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
f120: 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
f130: 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
f140: 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
f150: 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
f160: 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
f170: 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
f180: 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  n..**.** Calling
f190: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
f1a0: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
f1b0: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
f1c0: 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
f1d0: 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
f1e0: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
f1f0: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
f200: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
f210: 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
f220: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
f230: 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
f240: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
f250: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
f260: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
f270: 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
f280: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75  ntext..**.** Thu
f290: 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
f2a0: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
f2b0: 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
f2c0: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
f2d0: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
f2e0: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
f2f0: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
f300: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
f310: 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
f320: 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
f330: 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74  level.  Within t
f340: 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
f350: 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
f360: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
f370: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
f380: 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
f390: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
f3a0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
f3b0: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
f3c0: 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
f3d0: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
f3e0: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
f3f0: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
f400: 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
f410: 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
f420: 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
f430: 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
f440: 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
f450: 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
f460: 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
f470: 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
f480: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53  context..**.** S
f490: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
f4a0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
f4b0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
f4c0: 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  and the.** [coun
f4d0: 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
f4e0: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
f4f0: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34  ments:.** [H1224
f500: 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a  1] [H12243].**.*
f510: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
f520: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
f530: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
f540: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f550: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
f560: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
f570: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
f580: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
f590: 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
f5a0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
f5b0: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
f5c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
f5d0: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
f5e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f5f0: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
f600: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48  Rows Modified {H
f610: 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a  12260} <S10600>.
f620: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
f630: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
f640: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
f650: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
f660: 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
f670: 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
f680: 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
f690: 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
f6a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
f6b0: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20   opened..** The 
f6c0: 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61  count includes a
f6d0: 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20  ll changes from 
f6e0: 61 6c 6c 20 0a 2a 2a 20 5b 43 52 45 41 54 45 20  all .** [CREATE 
f6f0: 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
f700: 72 5d 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f  r] contexts.  Ho
f710: 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
f720: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
f730: 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
f740: 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
f750: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
f760: 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
f770: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
f780: 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
f790: 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
f7a0: 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
f7b0: 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
f7c0: 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
f7d0: 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
f7e0: 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
f7f0: 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
f800: 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
f810: 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
f820: 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
f830: 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
f840: 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
f850: 65 64 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ed..** The chang
f860: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  es are counted a
f870: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74  s soon as the st
f880: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
f890: 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f  es them is.** co
f8a0: 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
f8b0: 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
f8c0: 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  le is passed to 
f8d0: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
f8e0: 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
f8f0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
f900: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
f910: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
f920: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
f930: 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  and the.** [coun
f940: 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
f950: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
f960: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36  ments:.** [H1226
f970: 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a  1] [H12263].**.*
f980: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
f990: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
f9a0: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
f9b0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f9c0: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
f9d0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
f9e0: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
f9f0: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
fa00: 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
fa10: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
fa20: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
fa30: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
fa40: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
fa50: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
fa60: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
fa70: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
fa80: 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32  ning Query {H122
fa90: 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a  70} <S30500>.**.
faa0: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
fab0: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
fac0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
fad0: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
fae0: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
faf0: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
fb00: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
fb10: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
fb20: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
fb30: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
fb40: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
fb50: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
fb60: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
fb70: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
fb80: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
fb90: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
fba0: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
fbb0: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
fbc0: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
fbd0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
fbe0: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
fbf0: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
fc00: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
fc10: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
fc20: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
fc30: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
fc40: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
fc50: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
fc60: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
fc70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fc80: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
fc90: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
fca0: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
fcb0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
fcc0: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
fcd0: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
fce0: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
fcf0: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
fd00: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
fd10: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
fd20: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
fd30: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
fd40: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
fd50: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
fd60: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
fd70: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
fd80: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
fd90: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
fda0: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
fdb0: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
fdc0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
fdd0: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  PT]..** If the i
fde0: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
fdf0: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
fe00: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
fe10: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
fe20: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
fe30: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
fe40: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
fe50: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
fe60: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
fe70: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
fe80: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ally..**.** The 
fe90: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
fea0: 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
feb0: 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
fec0: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
fed0: 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
fee0: 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
fef0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
ff00: 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 6e  complete.  Any n
ff10: 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
ff20: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
ff30: 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
ff40: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ff50: 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
ff60: 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
ff70: 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
ff80: 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
ff90: 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
ffa0: 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
ffb0: 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
ffc0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
ffd0: 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
ffe0: 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74 65  .  New SQL state
fff0: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
10000 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
10010 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
10020 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
10030 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
10040 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
10050 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
10060 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 20 63 61  rrupt()..** A ca
10070 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
10080 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
10090 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
100a0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
100b0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
100c0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
100d0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
100e0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
100f0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
10100 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
10110 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
10120 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
10130 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
10140 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31  ents:.** [H12271
10150 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a  ] [H12272].**.**
10160 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
10170 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
10180 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
10190 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
101a0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
101b0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
101c0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
101d0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
101e0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
101f0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
10200 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
10210 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
10220 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
10230 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30   {H10510} <S7020
10240 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
10250 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
10260 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
10270 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
10280 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
10290 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
102a0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
102b0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
102c0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
102d0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
102e0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
102f0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
10300 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
10310 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
10320 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65   parsing.  These
10330 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
10340 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
10350 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
10360 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
10370 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
10380 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69  .  A statement i
10390 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
103a0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
103b0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
103c0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
103d0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
103e0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
103f0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
10400 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
10410 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
10420 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
10430 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
10440 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
10450 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
10460 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
10470 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
10480 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
10490 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
104a0 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
104b0 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
104c0 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
104d0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
104e0 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
104f0 69 6e 61 74 6f 72 2e 20 20 57 68 69 74 65 73 70  inator.  Whitesp
10500 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
10510 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
10520 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
10530 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
10540 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
10550 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
10560 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
10570 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
10580 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
10590 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
105a0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
105b0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
105c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
105d0 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
105e0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
105f0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
10600 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
10610 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
10620 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
10630 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
10640 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
10650 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
10660 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
10670 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
10680 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
10690 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
106a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
106b0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
106c0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
106d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
106e0 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
106f0 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
10700 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
10710 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
10720 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
10730 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
10740 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
10750 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
10760 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
10770 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
10780 6d 70 6c 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65  mplete..**.** Re
10790 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30  quirements: [H10
107a0 35 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a  511] [H10512].**
107b0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
107c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
107d0 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
107e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
107f0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
10800 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
10810 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
10820 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
10830 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
10840 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
10850 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
10860 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
10870 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
10880 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
10890 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
108a0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
108b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
108c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
108d0 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
108e0 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
108f0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
10900 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30   {H12310} <S4040
10910 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
10920 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
10930 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
10940 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
10950 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
10960 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
10970 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
10980 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
10990 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
109a0 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
109b0 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
109c0 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
109d0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
109e0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
109f0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
10a00 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
10a10 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
10a20 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
10a30 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
10a40 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63  k. If the busy c
10a50 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
10a60 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
10a70 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
10a80 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
10a90 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
10aa0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
10ab0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61  gument to the ha
10ac0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
10ad0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
10ae0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
10af0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
10b00 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
10b10 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
10b20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
10b30 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61  ent to.** the ha
10b40 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
10b50 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
10b60 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
10b70 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
10b80 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
10b90 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
10ba0 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a   event.  If the.
10bb0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
10bc0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
10bd0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
10be0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
10bf0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
10c00 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
10c10 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
10c20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
10c30 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
10c40 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
10c50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
10c60 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
10c70 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
10c80 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
10c90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
10ca0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
10cb0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
10cc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
10cd0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
10ce0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
10cf0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
10d00 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
10d10 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
10d20 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
10d30 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74  n. If SQLite det
10d40 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
10d50 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
10d60 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
10d70 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
10d80 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
10d90 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
10da0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
10db0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
10dc0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
10dd0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
10de0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
10df0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
10e00 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
10e10 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
10e20 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
10e30 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
10e40 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
10e50 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
10e60 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
10e70 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
10e80 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
10e90 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
10ea0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
10eb0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
10ec0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
10ed0 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
10ee0 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
10ef0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
10f00 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
10f10 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
10f20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
10f30 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
10f40 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
10f50 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
10f60 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
10f70 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
10f80 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
10f90 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
10fa0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
10fb0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
10fc0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
10fd0 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
10fe0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
10ff0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
11000 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
11010 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
11020 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
11030 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
11040 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
11050 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
11060 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
11070 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
11080 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
11090 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
110a0 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
110b0 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
110c0 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
110d0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
110e0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
110f0 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
11100 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
11110 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
11120 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
11130 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
11140 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
11150 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
11160 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
11170 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
11180 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
11190 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
111a0 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
111b0 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
111c0 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
111d0 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
111e0 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
111f0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
11200 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
11210 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
11220 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69  * readers.  If i
11230 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
11240 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
11250 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
11260 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
11270 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
11280 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
11290 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
112a0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
112b0 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
112c0 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
112d0 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
112e0 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
112f0 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
11300 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
11310 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
11320 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
11330 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
11340 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
11350 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
11360 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
11370 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
11380 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
11390 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
113a0 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
113b0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
113c0 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
113d0 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
113e0 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
113f0 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
11400 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
11410 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
11420 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
11430 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
11440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11450 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
11460 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
11470 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
11480 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
11490 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  ler.  Note that 
114a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
114b0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
114c0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
114d0 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
114e0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
114f0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
11500 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
11510 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
11520 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
11530 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
11540 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
11550 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
11560 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
11570 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
11580 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
11590 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
115a0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
115b0 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 31 32  ** [H12311] [H12
115c0 33 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48  312] [H12314] [H
115d0 31 32 33 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a  12316] [H12318].
115e0 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  **.** A busy han
115f0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
11600 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
11610 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
11620 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
11630 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
11640 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
11650 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
11660 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
11670 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
11680 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
11690 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
116a0 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
116b0 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33  sy Timeout {H123
116c0 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a  40} <S40410>.**.
116d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
116e0 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
116f0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
11700 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
11710 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
11720 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
11730 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
11740 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
11750 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a  d.  The handler.
11760 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
11770 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
11780 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
11790 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
117a0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
117b0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b  e accumulated. {
117c0 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d  H12343} After "m
117d0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
117e0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
117f0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
11800 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
11810 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
11820 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
11830 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
11840 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
11850 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
11860 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
11870 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
11880 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
11890 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
118a0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
118b0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
118c0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
118d0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
118e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
118f0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
11900 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11910 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
11920 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
11930 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
11940 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
11950 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
11960 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
11970 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
11980 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
11990 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
119a0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
119b0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a  er is cleared..*
119c0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
119d0 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b  s:.** [H12341] [
119e0 48 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34 5d  H12343] [H12344]
119f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
11a00 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
11a10 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
11a20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11a30 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
11a40 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
11a50 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 33 37  g Queries {H1237
11a60 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S10000>.**.*
11a70 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
11a80 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
11a90 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
11aa0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
11ab0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
11ac0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11ad0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
11ae0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
11af0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
11b00 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
11b10 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
11b20 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
11b30 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
11b40 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
11b50 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
11b60 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
11b70 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
11b80 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
11b90 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
11ba0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
11bb0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
11bc0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
11bd0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
11be0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
11bf0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
11c00 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
11c10 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
11c20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
11c30 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
11c40 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
11c50 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
11c60 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
11c70 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
11c80 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
11c90 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
11ca0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
11cb0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
11cc0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
11cd0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
11ce0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
11cf0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
11d00 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
11d10 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
11d20 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
11d30 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
11d40 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
11d50 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
11d60 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
11d70 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
11d80 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
11d90 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
11da0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
11db0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
11dc0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
11dd0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
11de0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
11df0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
11e00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
11e10 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
11e20 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
11e30 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
11e40 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
11e50 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
11e60 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
11e70 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
11e80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
11e90 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
11ea0 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
11eb0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
11ec0 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
11ed0 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
11ee0 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
11ef0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
11f00 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
11f10 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
11f20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
11f30 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
11f40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
11f50 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
11f60 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
11f70 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
11f80 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
11f90 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
11fa0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
11fb0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
11fc0 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
11fd0 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
11fe0 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
11ff0 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
12000 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
12010 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
12020 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
12030 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
12040 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
12050 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
12060 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
12070 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
12080 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
12090 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
120a0 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
120b0 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
120c0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
120d0 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
120e0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
120f0 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
12100 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
12110 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
12120 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12130 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
12140 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
12150 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
12160 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
12170 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
12180 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
12190 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
121a0 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
121b0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
121c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
121d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
121e0 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
121f0 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
12200 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
12210 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
12220 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
12230 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
12240 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
12250 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
12260 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ter.  It returns
12270 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
12280 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
12290 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
122a0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
122b0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61  .** After the ca
122c0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68  lling function h
122d0 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
122e0 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74  g the result, it
122f0 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20   should.** pass 
12300 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
12310 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
12320 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
12330 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
12340 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
12350 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
12360 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
12370 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
12380 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
12390 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
123a0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
123b0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
123c0 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
123d0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
123e0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
123f0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
12400 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
12410 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
12420 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
12430 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
12440 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
12450 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
12460 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
12470 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
12480 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
12490 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
124a0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
124b0 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
124c0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
124d0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
124e0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
124f0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
12500 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
12510 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
12520 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
12530 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
12540 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
12550 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
12560 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
12570 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
12580 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
12590 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
125a0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
125b0 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
125c0 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
125d0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
125e0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
125f0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20  3_errcode()] or 
12600 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
12610 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
12620 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33  ements:.** [H123
12630 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48 31  71] [H12373] [H1
12640 32 33 37 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b  2374] [H12376] [
12650 48 31 32 33 37 39 5d 20 5b 48 31 32 33 38 32 5d  H12379] [H12382]
12660 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12670 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
12680 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
12690 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
126a0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
126b0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
126c0 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
126d0 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
126e0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
126f0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
12700 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
12710 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
12720 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
12730 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
12740 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
12750 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
12760 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
12770 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
12780 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
12790 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
127a0 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
127b0 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
127c0 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
127d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
127e0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
127f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
12800 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
12810 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
12820 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30  unctions {H17400
12830 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30  } <S70000><S2000
12840 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
12850 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
12860 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
12870 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
12880 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
12890 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
128a0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
128b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
128c0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
128d0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
128e0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
128f0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
12900 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
12910 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
12920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
12930 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
12940 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
12950 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
12960 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
12970 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
12980 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f  ree()].  Both ro
12990 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
129a0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
129b0 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
129c0 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
129d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
129e0 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
129f0 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
12a00 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
12a10 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   In sqlite3_snpr
12a20 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
12a30 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
12a40 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
12a50 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
12a60 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
12a70 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
12a80 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
12a90 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
12aa0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
12ab0 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
12ac0 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
12ad0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12ae0 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
12af0 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
12b00 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
12b10 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
12b20 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
12b30 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  ().  This is an.
12b40 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
12b50 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
12b60 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
12b70 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
12b80 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
12b90 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61  ibility.  Note a
12ba0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
12bb0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
12bc0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
12bd0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
12be0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
12bf0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
12c00 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
12c10 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
12c20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69  buffer.  We admi
12c30 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
12c40 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
12c50 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
12c60 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
12c70 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
12c80 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
12c90 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
12ca0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
12cb0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
12cc0 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
12cd0 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
12ce0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  ility..**.** As 
12cf0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
12d00 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
12d10 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
12d20 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
12d30 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
12d40 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
12d50 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
12d60 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66  rminated.  The f
12d70 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
12d80 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
12d90 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
12da0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
12db0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
12dc0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
12dd0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
12de0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
12df0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
12e00 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
12e10 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
12e20 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
12e30 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
12e40 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
12e50 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
12e60 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
12e70 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
12e80 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
12e90 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
12ea0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
12eb0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
12ec0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
12ed0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
12ee0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
12ef0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
12f00 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
12f10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
12f20 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
12f30 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
12f40 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
12f50 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
12f60 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
12f70 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
12f80 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
12f90 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
12fa0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
12fb0 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
12fc0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
12fd0 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
12fe0 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
12ff0 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
13000 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
13010 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
13020 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
13030 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
13040 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
13050 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
13060 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
13070 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
13080 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
13090 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
130a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
130b0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
130c0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
130d0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
130e0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
130f0 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
13100 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
13110 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
13120 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
13130 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
13140 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
13150 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
13160 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
13170 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
13180 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
13190 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
131a0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
131b0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
131c0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
131d0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
131e0 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
131f0 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
13200 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
13210 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
13220 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
13230 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
13240 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
13250 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
13260 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
13270 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
13280 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
13290 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
132a0 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
132b0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
132c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
132d0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
132e0 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
132f0 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
13300 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
13310 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
13320 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
13330 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
13340 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
13350 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
13360 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
13370 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
13380 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
13390 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
133a0 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
133b0 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
133c0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
133d0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
133e0 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
133f0 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
13400 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
13410 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
13420 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ral..**.** The %
13430 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
13440 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
13450 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
13460 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
13470 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
13480 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
13490 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
134a0 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
134b0 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
134c0 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
134d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
134e0 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
134f0 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
13500 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
13510 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
13520 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
13530 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  on.  So, for exa
13540 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
13550 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
13560 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
13570 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
13580 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
13590 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
135a0 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
135b0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
135c0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
135d0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
135e0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
135f0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
13600 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
13610 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
13620 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
13630 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
13640 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
13650 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
13660 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
13670 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
13680 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
13690 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
136a0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
136b0 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
136c0 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
136d0 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
136e0 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
136f0 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
13700 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
13710 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
13720 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
13730 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
13740 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
13750 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
13760 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20  ts:.** [H17403] 
13770 5b 48 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37  [H17406] [H17407
13780 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ].*/.char *sqlit
13790 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
137a0 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
137b0 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
137c0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
137d0 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
137e0 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
137f0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
13800 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
13810 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13820 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
13830 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37  n Subsystem {H17
13840 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  300} <S20000>.**
13850 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
13860 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20  ore  uses these 
13870 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
13880 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
13890 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
138a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
138b0 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
138c0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
138d0 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
138e0 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
138f0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
13900 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
13910 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
13920 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
13930 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
13940 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
13950 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
13960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
13970 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
13980 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
13990 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
139a0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
139b0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
139c0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
139d0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
139e0 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ter..** If sqlit
139f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
13a00 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
13a10 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
13a20 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
13a30 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
13a40 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61  nter.  If the pa
13a50 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
13a60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13a70 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
13a80 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
13a90 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
13aa0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
13ab0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  nter..**.** Call
13ac0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
13ad0 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
13ae0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
13af0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
13b00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
13b10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
13b20 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
13b30 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
13b40 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
13b50 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  used.  The sqlit
13b60 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
13b70 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
13b80 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
13b90 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
13ba0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
13bb0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
13bc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
13bd0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
13be0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
13bf0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
13c00 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
13c10 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
13c20 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
13c30 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
13c40 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
13c50 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
13c60 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
13c70 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
13c80 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
13c90 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
13ca0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
13cb0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
13cc0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
13cd0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
13ce0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
13cf0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
13d00 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
13d10 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
13d20 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
13d30 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
13d40 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
13d50 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
13d60 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
13d70 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
13d80 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
13d90 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
13da0 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
13db0 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
13dc0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
13dd0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
13de0 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
13df0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
13e00 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
13e10 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  t.** parameter. 
13e20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
13e30 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
13e40 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
13e50 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
13e60 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
13e70 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
13e80 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
13e90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
13ea0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
13eb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13ec0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
13ed0 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65  loc()..** If the
13ee0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13ef0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
13f00 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
13f10 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
13f20 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
13f30 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
13f40 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
13f50 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
13f60 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
13f70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13f80 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
13f90 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65  loc()..** sqlite
13fa0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
13fb0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
13fc0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
13fd0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
13fe0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
13ff0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
14000 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
14010 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
14020 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20  .** If M is the 
14030 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
14040 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
14050 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
14060 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
14070 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
14080 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
14090 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
140a0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
140b0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
140c0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
140d0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
140e0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73  s freed..** If s
140f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14100 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
14110 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
14120 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
14130 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
14140 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
14150 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
14160 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
14170 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
14180 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
14190 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
141a0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
141b0 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  y. {END}.**.** T
141c0 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65  he default imple
141d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
141e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
141f0 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
14200 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28  s.** the malloc(
14210 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
14220 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
14230 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
14240 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b   C library..** {
14250 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c  H17382} However,
14260 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
14270 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
14280 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59  ** SQLITE_MEMORY
14290 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e  _SIZE=<i>NNN</i>
142a0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
142b0 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e  macro (where <i>
142c0 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e  NNN</i>.** is an
142d0 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20   integer), then 
142e0 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20  SQLite create a 
142f0 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20  static array of 
14300 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e  at least.** <i>N
14310 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20  NN</i> bytes in 
14320 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68  size and uses th
14330 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c  at array for all
14340 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a   of its dynamic.
14350 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
14360 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44  tion needs. {END
14370 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  }  Additional me
14380 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
14390 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65  ptions.** may be
143a0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
143b0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
143c0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
143d0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
143e0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
143f0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
14400 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
14410 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
14420 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
14430 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
14440 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
14450 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
14460 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
14470 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
14480 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
14490 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
144a0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
144b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
144c0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
144d0 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
144e0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
144f0 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
14500 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
14510 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
14520 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
14530 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
14540 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
14550 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
14560 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
14570 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
14580 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
14590 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
145a0 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
145b0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
145c0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
145d0 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
145e0 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
145f0 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
14600 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
14610 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
14620 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
14630 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
14640 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
14650 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
14660 2a 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37  ** [H17303] [H17
14670 33 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48  304] [H17305] [H
14680 31 37 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20  17306] [H17310] 
14690 5b 48 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35  [H17312] [H17315
146a0 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48  ] [H17318].** [H
146b0 31 37 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20  17321] [H17322] 
146c0 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54  [H17323].**.** T
146d0 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
146e0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
146f0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
14700 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
14710 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
14720 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
14730 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
14740 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
14750 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
14760 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14770 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
14780 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
14790 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
147a0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
147b0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
147c0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
147d0 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
147e0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
147f0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
14800 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
14810 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
14820 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14830 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
14840 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
14850 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
14860 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
14870 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
14880 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
14890 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
148a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
148b0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
148c0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
148d0 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31   {H17370} <S3021
148e0 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0>.**.** SQLite 
148f0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
14900 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
14910 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
14920 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
14930 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
14940 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
14950 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
14960 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14970 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
14980 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
14990 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
149a0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
149b0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  em..**.** Requir
149c0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33  ements:.** [H173
149d0 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 31  71] [H17373] [H1
149e0 37 33 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a  7374] [H17375].*
149f0 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
14a00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
14a10 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
14a20 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
14a30 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
14a40 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
14a50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14a60 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
14a70 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
14a80 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30  r {H17390} <S200
14a90 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
14aa0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
14ab0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
14ac0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
14ad0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
14ae0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
14af0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
14b00 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
14b10 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
14b20 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
14b30 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
14b40 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
14b50 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
14b60 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
14b70 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
14b80 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
14b90 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
14ba0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
14bb0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
14bc0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
14bd0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
14be0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
14bf0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
14c00 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
14c10 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20   A call to this 
14c20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
14c30 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
14c40 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
14c50 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69   P..**.** The fi
14c60 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
14c70 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
14c80 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
14c90 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
14ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
14cb0 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
14cc0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
14cd0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
14ce0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
14cf0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
14d00 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
14d10 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
14d20 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75  * On all subsequ
14d30 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
14d40 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
14d50 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
14d60 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
14d70 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
14d80 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
14d90 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
14da0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
14db0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
14dc0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39  ments:.** [H1739
14dd0 32 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  2].*/.void sqlit
14de0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
14df0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
14e00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14e10 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
14e20 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
14e30 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53  acks {H12500} <S
14e40 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  70100>.**.** Thi
14e50 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
14e60 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
14e70 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
14e80 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
14e90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14ea0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
14eb0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
14ec0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74  ment..** The aut
14ed0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14ee0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
14ef0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
14f00 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
14f10 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
14f20 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
14f30 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
14f40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
14f50 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
14f60 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
14f70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14f80 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61  16_v2()].  At va
14f90 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
14fa0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
14fb0 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
14fc0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
14fd0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
14fe0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
14ff0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
15000 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15010 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
15020 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
15030 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
15040 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69  ed.  The authori
15050 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
15060 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
15070 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
15080 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
15090 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
150a0 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
150b0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
150c0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
150d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
150e0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
150f0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
15100 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
15110 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
15120 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
15130 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
15140 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
15150 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
15160 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
15170 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
15180 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
15190 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
151a0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
151b0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
151c0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
151d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
151e0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
151f0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
15200 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
15210 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
15220 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
15230 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
15240 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
15250 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
15260 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
15270 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
15280 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57  uested is ok.  W
15290 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
152a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
152b0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
152c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
152d0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
152e0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
152f0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
15300 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
15310 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
15320 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
15330 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
15340 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
15350 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
15360 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15370 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15380 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
15390 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
153a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
153b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
153c0 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
153d0 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  ce. The second p
153e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
153f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
15400 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
15410 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
15420 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
15430 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
15440 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
15450 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
15460 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
15470 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
15480 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
15490 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
154a0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
154b0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
154c0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
154d0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
154e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
154f0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  orized..**.** If
15500 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
15510 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
15520 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
15530 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
15540 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
15550 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
15560 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
15570 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
15580 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
15590 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
155a0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
155b0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
155c0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
155d0 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
155e0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
155f0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
15600 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
15610 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
15620 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
15630 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
15640 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
15650 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
15660 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
15670 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 61 63 74  e..** If the act
15680 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
15690 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
156a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
156b0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
156c0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
156d0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
156e0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
156f0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
15700 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
15710 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
15720 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
15730 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
15740 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
15750 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
15760 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
15770 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
15780 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
15790 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
157a0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
157b0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
157c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
157d0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
157e0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
157f0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
15800 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
15810 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
15820 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
15830 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
15840 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
15850 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
15860 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
15870 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
15880 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
15890 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
158a0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
158b0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
158c0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
158d0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
158e0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
158f0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
15900 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
15910 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
15920 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
15930 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
15940 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
15950 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
15960 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
15970 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
15980 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
15990 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
159a0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
159b0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
159c0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
159d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
159e0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
159f0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
15a00 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
15a10 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
15a20 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
15a30 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
15a40 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
15a50 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
15a60 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
15a70 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
15a80 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
15a90 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
15aa0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
15ab0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
15ac0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
15ad0 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20  r..**.** Only a 
15ae0 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
15af0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
15b00 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
15b10 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
15b20 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
15b30 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
15b40 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
15b50 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
15b60 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44  revious call.  D
15b70 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
15b80 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
15b90 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
15ba0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
15bb0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
15bc0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
15bd0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
15be0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
15bf0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
15c00 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
15c10 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
15c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
15c30 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
15c40 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15c50 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
15c60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15c70 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
15c80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
15c90 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
15ca0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
15cb0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
15cc0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
15cd0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
15ce0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  raph..**.** When
15cf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15d00 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
15d10 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
15d20 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
15d30 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
15d40 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
15d50 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
15d60 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
15d70 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
15d80 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
15d90 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
15da0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
15db0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
15dc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15dd0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
15de0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
15df0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
15e00 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
15e10 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
15e20 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15e30 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
15e40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15e50 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
15e60 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
15e70 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
15e80 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
15e90 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
15ea0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
15eb0 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
15ec0 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
15ed0 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
15ee0 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
15ef0 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
15f00 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
15f10 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
15f20 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
15f30 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
15f40 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  hange..**.** Req
15f50 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
15f60 31 32 35 30 31 5d 20 5b 48 31 32 35 30 32 5d 20  12501] [H12502] 
15f70 5b 48 31 32 35 30 33 5d 20 5b 48 31 32 35 30 34  [H12503] [H12504
15f80 5d 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 35  ] [H12505] [H125
15f90 30 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 31  06] [H12507] [H1
15fa0 32 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31  2510].** [H12511
15fb0 5d 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 35  ] [H12512] [H125
15fc0 32 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 31  20] [H12521] [H1
15fd0 32 35 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2522].*/.int sql
15fe0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
15ff0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
16000 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
16010 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
16020 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
16030 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
16040 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
16050 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
16060 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16070 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
16080 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39  urn Codes {H1259
16090 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a  0} <H12500>.**.*
160a0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
160b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
160c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
160d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
160e0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
160f0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
16100 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
16110 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
16120 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
16130 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
16140 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
16150 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
16160 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
16170 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
16180 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
16190 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
161a0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
161b0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
161c0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
161d0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
161e0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
161f0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
16200 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
16210 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
16220 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
16230 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
16240 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
16250 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
16260 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
16270 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
16280 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31  des {H12550} <H1
16290 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2500>.**.** The 
162a0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
162b0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
162c0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
162d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
162e0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
162f0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
16300 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
16310 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
16320 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
16330 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16340 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
16350 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
16360 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
16370 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
16380 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
16390 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
163a0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
163b0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
163c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
163d0 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
163e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
163f0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
16400 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
16410 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
16420 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
16430 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
16440 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
16450 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
16460 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
16470 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
16480 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
16490 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
164a0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
164b0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
164c0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
164d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
164e0 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
164f0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
16500 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16510 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
16520 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
16530 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
16540 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
16550 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20  cable.  The 6th 
16560 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16570 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16580 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
16590 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
165a0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
165b0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
165c0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
165d0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
165e0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
165f0 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
16600 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
16610 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
16620 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a   SQL code..**.**
16630 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
16640 2a 20 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 35  * [H12551] [H125
16650 35 32 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 31  52] [H12553] [H1
16660 32 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  2554].*/./******
16670 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16680 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16690 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
166a0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
166b0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
166c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
166d0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
166e0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
166f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
16700 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16710 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
16720 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
16730 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
16740 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16750 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16760 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
16770 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
16780 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
16790 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
167a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
167b0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
167c0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
167d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
167e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
167f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16800 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
16810 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
16820 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
16830 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
16840 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16850 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
16860 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
16870 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
16880 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
16890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
168a0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
168b0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
168c0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
168d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
168e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
168f0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
16900 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
16910 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
16920 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
16930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16940 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
16950 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
16960 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
16970 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
16980 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
16990 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
169a0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
169b0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
169c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
169d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
169e0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
169f0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
16a00 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
16a10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16a20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
16a30 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
16a40 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
16a50 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
16a60 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
16a70 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
16a80 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
16a90 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
16aa0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
16ab0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
16ac0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
16ad0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
16ae0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
16af0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
16b00 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
16b10 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
16b20 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
16b30 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
16b40 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
16b50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16b60 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
16b70 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
16b80 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
16b90 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
16ba0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16bb0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
16bc0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
16bd0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
16be0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
16bf0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16c00 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
16c10 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
16c20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
16c30 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16c40 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16c50 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
16c60 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
16c70 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
16c80 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
16c90 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
16ca0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
16cb0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
16cc0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
16cd0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
16ce0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16cf0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
16d00 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
16d10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
16d20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
16d30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16d40 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
16d50 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
16d60 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
16d70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
16d80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d90 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
16da0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
16db0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
16dc0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
16dd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16de0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
16df0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
16e00 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
16e10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
16e20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16e30 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
16e40 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
16e50 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
16e60 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
16e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
16e80 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
16e90 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
16ea0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
16eb0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
16ec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
16ed0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
16ee0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
16ef0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
16f00 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16f10 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
16f20 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
16f30 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
16f40 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
16f50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
16f60 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
16f70 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
16f80 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
16f90 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
16fa0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
16fb0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
16fc0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
16fd0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
16fe0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
16ff0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
17000 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
17010 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
17020 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
17030 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
17040 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
17050 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
17060 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
17070 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
17080 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
17090 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
170a0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
170b0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
170c0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
170d0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
170e0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
170f0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
17100 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20  ctions {H12280} 
17110 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45  <S60400>.** EXPE
17120 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
17130 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
17140 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
17150 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
17160 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
17170 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
17180 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
17190 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
171a0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  tements..**.** T
171b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
171c0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
171d0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
171e0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
171f0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
17200 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
17210 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
17220 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
17230 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65  _step()]..** The
17240 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17250 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  s a UTF-8 render
17260 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ing of the SQL s
17270 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a  tatement text.**
17280 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
17290 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
172a0 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74  xecuting.  Addit
172b0 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  ional callbacks 
172c0 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
172d0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
172e0 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
172f0 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
17300 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
17310 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
17320 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
17330 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
17340 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
17350 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
17360 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
17370 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
17380 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
17390 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
173a0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
173b0 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65  es.  The profile
173c0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
173d0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
173e0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
173f0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
17400 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
17410 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
17420 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
17430 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a  nt took to run..
17440 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
17450 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20  ts:.** [H12281] 
17460 5b 48 31 32 32 38 32 5d 20 5b 48 31 32 32 38 33  [H12282] [H12283
17470 5d 20 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 32  ] [H12284] [H122
17480 38 35 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 31  85] [H12287] [H1
17490 32 32 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a  2288] [H12289].*
174a0 2a 20 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51  * [H12290].*/.SQ
174b0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
174c0 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
174d0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
174e0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
174f0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
17500 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
17510 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
17520 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
17530 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
17540 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
17550 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
17560 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
17570 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
17580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
17590 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
175a0 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c  backs {H12910} <
175b0 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60400>.**.** Th
175c0 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69  is routine confi
175d0 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  gures a callback
175e0 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a   function - the.
175f0 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  ** progress call
17600 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69  back - that is i
17610 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
17620 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a  lly during long.
17630 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ** running calls
17640 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
17650 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
17660 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  tep()] and.** [s
17670 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
17680 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ()].  An example
17690 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
176a0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
176b0 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
176c0 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
176d0 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
176e0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
176f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17700 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
17710 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
17720 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
17730 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
17740 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
17750 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
17760 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
17770 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
17780 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
17790 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
177a0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
177b0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
177c0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
177d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
177e0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
177f0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
17800 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
17810 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
17820 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
17830 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
17840 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
17850 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
17860 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
17870 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
17880 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
17890 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  graph..**.** Req
178a0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
178b0 31 32 39 31 31 5d 20 5b 48 31 32 39 31 32 5d 20  12911] [H12912] 
178c0 5b 48 31 32 39 31 33 5d 20 5b 48 31 32 39 31 34  [H12913] [H12914
178d0 5d 20 5b 48 31 32 39 31 35 5d 20 5b 48 31 32 39  ] [H12915] [H129
178e0 31 36 5d 20 5b 48 31 32 39 31 37 5d 20 5b 48 31  16] [H12917] [H1
178f0 32 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  2918].**.*/.void
17900 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
17910 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
17920 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
17930 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
17940 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17950 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
17960 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
17970 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30  on {H12700} <S40
17980 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  200>.**.** These
17990 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
179a0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
179b0 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d  e file whose nam
179c0 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  e is given by th
179d0 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72  e.** filename ar
179e0 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65  gument. The file
179f0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
17a00 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
17a10 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
17a20 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
17a30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
17a40 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
17a50 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
17a60 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
17a70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
17a80 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  . A [database co
17a90 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
17aa0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
17ab0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
17ac0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
17ad0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
17ae0 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
17af0 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
17b00 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
17b10 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
17b20 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
17b30 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
17b40 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
17b50 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
17b60 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
17b70 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
17b80 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
17b90 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61  ect. If the data
17ba0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
17bb0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
17bc0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
17bd0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
17be0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
17bf0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
17c00 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
17c10 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b  urned.  The.** [
17c20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
17c30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
17c40 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
17c50 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
17c60 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
17c70 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
17c80 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
17c90 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  he error..**.** 
17ca0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
17cb0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
17cc0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
17cd0 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
17ce0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
17cf0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
17d00 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
17d10 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
17d20 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
17d30 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
17d40 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
17d50 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
17d60 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
17d70 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
17d80 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
17d90 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
17da0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
17db0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
17dc0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
17dd0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
17de0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
17df0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
17e00 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
17e10 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
17e20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
17e30 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
17e40 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
17e50 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
17e60 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
17e70 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
17e80 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
17e90 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
17ea0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
17eb0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
17ec0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66  nnection.  The f
17ed0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63  lags parameter c
17ee0 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
17ef0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
17f00 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
17f10 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
17f20 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
17f30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
17f40 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  TEX] or [SQLITE_
17f50 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
17f60 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c  flags:.**.** <dl
17f70 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45  >.** <dt>[SQLITE
17f80 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
17f90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
17fa0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
17fb0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
17fc0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
17fd0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
17fe0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
17ff0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
18000 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  turned.</dd>.**.
18010 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f  ** <dt>[SQLITE_O
18020 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
18030 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
18040 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
18050 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
18060 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
18070 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
18080 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
18090 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
180a0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
180b0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
180c0 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
180d0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
180e0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
180f0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
18100 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
18110 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  rned.</dd>.**.**
18120 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
18130 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
18140 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
18150 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
18160 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
18170 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
18180 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
18190 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69  and is creates i
181a0 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  t if.** it does 
181b0 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
181c0 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
181d0 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
181e0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
181f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
18200 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
18210 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20  en16().</dd>.** 
18220 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
18230 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
18240 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
18250 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
18260 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
18270 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
18280 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ove or one of th
18290 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  e combinations s
182a0 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69  hown above combi
182b0 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ned.** with the 
182c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
182d0 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45  UTEX] or [SQLITE
182e0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
182f0 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20   flags,.** then 
18300 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
18310 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
18320 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   If the [SQLITE_
18330 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
18340 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
18350 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
18360 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
18370 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
18380 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
18390 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
183a0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
183b0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
183c0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
183d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
183e0 74 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74  tart-time.  If t
183f0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
18400 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
18410 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
18420 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18430 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
18440 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
18450 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
18460 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
18470 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
18480 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
18490 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
184a0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
184b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
184c0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
184d0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
184e0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
184f0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
18500 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
18510 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
18520 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d  tion.  This in-m
18530 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
18540 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
18550 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
18560 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
18570 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
18580 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
18590 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
185a0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
185b0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
185c0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
185d0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
185e0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
185f0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
18600 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
18610 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
18620 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
18630 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
18640 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
18650 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
18660 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
18670 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
18680 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
18690 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66  iguity..**.** If
186a0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
186b0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
186c0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
186d0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
186e0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
186f0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
18700 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64    This private d
18710 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
18720 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
18730 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
18740 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
18750 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
18760 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
18770 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
18780 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
18790 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
187a0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
187b0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
187c0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
187d0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
187e0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
187f0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
18800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18810 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49  n should use.  I
18820 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
18830 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
18840 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
18850 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
18860 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
18870 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
18880 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
18890 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
188a0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
188b0 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
188c0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
188d0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
188e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
188f0 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
18900 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
18910 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
18920 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
18930 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
18940 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
18950 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
18960 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
18970 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
18980 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
18990 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
189a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
189b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
189c0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  2()..**.** Requi
189d0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
189e0 37 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48  701] [H12702] [H
189f0 31 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20  12703] [H12704] 
18a00 5b 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37  [H12706] [H12707
18a10 5d 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37  ] [H12709] [H127
18a20 31 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20  11].** [H12712] 
18a30 5b 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34  [H12713] [H12714
18a40 5d 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37  ] [H12717] [H127
18a50 31 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31  19] [H12721] [H1
18a60 32 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2723].*/.int sql
18a70 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
18a80 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
18a90 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
18aa0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
18ab0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
18ac0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
18ad0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
18ae0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
18af0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
18b00 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
18b10 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
18b20 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
18b30 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
18b40 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
18b50 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
18b60 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
18b70 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
18b80 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
18b90 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
18ba0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
18bb0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
18bc0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
18bd0 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
18be0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
18bf0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
18c00 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
18c10 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
18c20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
18c30 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
18c40 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
18c50 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
18c60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
18c70 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
18c80 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d  essages {H12800}
18c90 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60200>.**.** 
18ca0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
18cb0 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
18cc0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
18cd0 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
18ce0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
18cf0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
18d00 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
18d10 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
18d20 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
18d30 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
18d40 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
18d50 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
18d60 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
18d70 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
18d80 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
18d90 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
18da0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
18db0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
18dc0 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
18dd0 65 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c  efined.  The sql
18de0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
18df0 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
18e00 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
18e10 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
18e20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
18e30 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
18e40 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
18e50 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
18e60 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
18e70 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
18e80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
18e90 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
18ea0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
18eb0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
18ec0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
18ed0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
18ee0 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
18ef0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
18f00 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
18f10 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20  y..** Memory to 
18f20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
18f30 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
18f40 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
18f50 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
18f60 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
18f70 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
18f80 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
18f90 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
18fa0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
18fb0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
18fc0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
18fd0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
18fe0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
18ff0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
19000 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
19010 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ions..**.** When
19020 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
19030 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
19040 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
19050 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
19060 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
19070 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
19080 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
19090 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
190a0 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
190b0 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
190c0 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
190d0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
190e0 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
190f0 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
19100 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
19110 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
19120 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
19130 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
19140 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
19150 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
19160 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
19170 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
19180 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
19190 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
191a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
191b0 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
191c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
191d0 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
191e0 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
191f0 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
19200 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
19210 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
19220 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
19230 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
19240 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
19250 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
19260 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
19270 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
19280 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
19290 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
192a0 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
192b0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
192c0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
192d0 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
192e0 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
192f0 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
19300 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
19310 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
19320 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
19330 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a  y not be set..**
19340 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
19350 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48  :.** [H12801] [H
19360 31 32 38 30 32 5d 20 5b 48 31 32 38 30 33 5d 20  12802] [H12803] 
19370 5b 48 31 32 38 30 37 5d 20 5b 48 31 32 38 30 38  [H12807] [H12808
19380 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e  ] [H12809].*/.in
19390 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
193a0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
193b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
193c0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
193d0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
193e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
193f0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
19400 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
19410 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
19420 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19430 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
19440 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
19450 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e  H13000} <H13010>
19460 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
19470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19480 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
19490 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
194a0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
194b0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
194c0 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
194d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
194e0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
194f0 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
19500 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
19510 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
19520 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
19530 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
19540 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
19550 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
19560 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
19570 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
19580 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
19590 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
195a0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
195b0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
195c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
195d0 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
195e0 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
195f0 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
19600 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
19610 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
19620 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
19630 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
19640 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
19650 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
19660 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
19670 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
19680 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
19690 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
196a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
196b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
196c0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
196d0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
196e0 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
196f0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
19700 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
19710 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
19720 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
19730 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
19740 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
19750 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
19760 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
19770 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
19780 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
19790 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
197a0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
197b0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
197c0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
197d0 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
197e0 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d   Limits {H12760}
197f0 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20600>.**.** 
19800 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
19810 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
19820 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
19830 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
19840 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
19850 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
19860 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
19870 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
19880 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
19890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
198a0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
198b0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
198c0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
198d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
198e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
198f0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
19900 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
19910 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
19920 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
19930 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
19940 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
19950 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
19960 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
19970 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  uct.  The functi
19980 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f  on returns the o
19990 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  ld limit..**.** 
199a0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
199b0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
199c0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
199d0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
199e0 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  * For the limit 
199f0 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
19a00 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
19a10 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
19a20 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
19a30 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62   bound].** set b
19a40 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  y a compile-time
19a50 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
19a60 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20  macro named .** 
19a70 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
19a80 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54  _MAX_XYZ]..** (T
19a90 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
19aa0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
19ab0 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
19ac0 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20  .** Attempts to 
19ad0 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
19ae0 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
19af0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
19b00 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
19b10 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
19b20 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a  d upper limit..*
19b30 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69  *.** Run time li
19b40 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
19b50 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
19b60 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
19b70 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
19b80 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
19b90 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
19ba0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
19bb0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
19bc0 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
19bd0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
19be0 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
19bf0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
19c00 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
19c10 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
19c20 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
19c30 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
19c40 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
19c50 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
19c60 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
19c70 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
19c80 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
19c90 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
19ca0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
19cb0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
19cc0 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
19cd0 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
19ce0 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
19cf0 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
19d00 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
19d10 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
19d20 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
19d30 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
19d40 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
19d50 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
19d60 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
19d70 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
19d80 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
19d90 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
19da0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
19db0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
19dc0 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
19dd0 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
19de0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
19df0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
19e00 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
19e10 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
19e20 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
19e30 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
19e40 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
19e50 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
19e60 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
19e70 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
19e80 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
19e90 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
19ea0 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20  ts:.** [H12762] 
19eb0 5b 48 31 32 37 36 36 5d 20 5b 48 31 32 37 36 39  [H12766] [H12769
19ec0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
19ed0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
19ee0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
19ef0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
19f00 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
19f10 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
19f20 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36   {H12790} <H1276
19f30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
19f40 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
19f50 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   {limit categori
19f60 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
19f70 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
19f80 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
19f90 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
19fa0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
19fb0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
19fc0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
19fd0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
19fe0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
19ff0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1a000 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
1a010 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
1a020 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
1a030 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
1a040 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
1a050 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
1a060 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
1a070 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1a080 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
1a090 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1a0a0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
1a0b0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
1a0c0 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a   table row.<dd>.
1a0d0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a0e0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
1a0f0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1a100 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1a110 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
1a120 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
1a130 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1a140 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
1a150 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1a160 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1a170 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
1a180 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
1a190 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
1a1a0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
1a1b0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
1a1c0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1a1d0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
1a1e0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
1a1f0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
1a200 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  use.</dd>.**.** 
1a210 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1a220 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
1a230 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1a240 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
1a250 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
1a260 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
1a270 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1a280 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1a290 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
1a2a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1a2b0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
1a2c0 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
1a2d0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1a2e0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1a2f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1a300 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1a310 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1a320 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1a330 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1a340 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1a350 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1a360 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1a370 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1a380 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a390 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1a3a0 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
1a3b0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1a3c0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
1a3d0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
1a3e0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1a3f0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1a400 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
1a410 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1a420 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
1a430 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1a440 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  s].</dd>.**.** <
1a450 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1a460 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
1a470 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1a480 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1a490 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
1a4a0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
1a4b0 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
1a4c0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
1a4d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1a4e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1a4f0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
1a500 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1a510 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76  imum number of v
1a520 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53  ariables in an S
1a530 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
1a540 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e  t can.** be boun
1a550 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  d.</dd>.** </dl>
1a560 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1a570 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1a580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a590 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1a5a0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1a5b0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1a5c0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1a5d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1a5e0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1a5f0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1a600 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1a610 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1a620 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1a630 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1a640 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1a650 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1a660 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1a670 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1a680 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1a690 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1a6a0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1a6b0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1a6c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1a6d0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1a6e0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1a6f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1a700 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1a710 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1a720 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1a730 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1a740 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f  R           9../
1a750 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1a760 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
1a770 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31  Statement {H1301
1a780 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b  0} <S10000>.** K
1a790 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
1a7a0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1a7b0 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
1a7c0 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
1a7d0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
1a7e0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
1a7f0 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
1a800 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
1a810 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1a820 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1a830 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
1a840 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
1a850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
1a860 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
1a870 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
1a880 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1a890 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1a8a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1a8b0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1a8c0 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
1a8d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a8e0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
1a8f0 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
1a900 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1a910 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
1a920 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
1a930 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
1a940 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
1a950 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1a960 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
1a970 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1a980 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1a990 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
1a9a0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
1a9b0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
1a9c0 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
1a9d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1a9e0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
1a9f0 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  16..**.** If the
1aa00 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1aa10 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1aa20 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
1aa30 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
1aa40 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
1aa50 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74  minator. If nByt
1aa60 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1aa70 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
1aa80 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
1aa90 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
1aaa0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57  ad from zSql.  W
1aab0 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
1aac0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
1aad0 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
1aae0 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
1aaf0 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
1ab00 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
1ab10 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
1ab20 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
1ab30 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
1ab40 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
1ab50 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
1ab60 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
1ab70 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
1ab80 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
1ab90 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
1aba0 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
1abb0 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
1abc0 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
1abd0 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
1abe0 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
1abf0 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
1ac00 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
1ac10 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
1ac20 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
1ac30 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
1ac40 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a  tor bytes..**.**
1ac50 20 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f   If pzTail is no
1ac60 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
1ac70 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
1ac80 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
1ac90 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
1aca0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
1acb0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
1acc0 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
1acd0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
1ace0 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
1acf0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
1ad00 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
1ad10 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
1ad20 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
1ad30 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
1ad40 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
1ad50 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
1ad60 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
1ad70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ad80 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
1ad90 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
1ada0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1adb0 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69  ()].  If there i
1adc0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
1add0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
1ade0 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69   NULL.  If the i
1adf0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
1ae00 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
1ae10 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
1ae20 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
1ae30 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
1ae40 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
1ae50 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
1ae60 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
1ae70 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
1ae80 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
1ae90 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
1aea0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
1aeb0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1aec0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
1aed0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1aee0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
1aef0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
1af00 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
1af10 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  s, [SQLITE_OK] i
1af20 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65  s returned, othe
1af30 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1af40 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1af50 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1af60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1af70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1af80 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
1af90 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
1afa0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
1afb0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
1afc0 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
1afd0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
1afe0 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
1aff0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1b000 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
1b010 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
1b020 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22  ged..** In the "
1b030 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1b040 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1b050 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1b060 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1b070 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1b080 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1b090 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
1b0a0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1b0b0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
1b0c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1b0d0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1b0e0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69  o.** behave a di
1b0f0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f  fferently in two
1b100 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1b110 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20  >.** <li>.** If 
1b120 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1b130 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
1b140 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
1b150 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
1b160 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
1b170 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
1b180 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1b190 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
1b1a0 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
1b1b0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1b1c0 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
1b1d0 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68  it again.  If th
1b1e0 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
1b1f0 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
1b200 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
1b210 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
1b220 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
1b230 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1b240 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
1b250 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1b260 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
1b270 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1b280 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  r, [SQLITE_SCHEM
1b290 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66  A] is.** now a f
1b2a0 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c  atal error.  Cal
1b2b0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
1b2c0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69  epare_v2()] agai
1b2d0 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20  n will not make 
1b2e0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20  the.** error go 
1b2f0 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65  away.  Note: use
1b300 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1b310 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ()] to find the 
1b320 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70  text.** of the p
1b330 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61  arsing error tha
1b340 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20  t results in an 
1b350 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1b360 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e  return..** </li>
1b370 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57  .**.** <li>.** W
1b380 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
1b390 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
1b3a0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
1b3b0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
1b3c0 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
1b3d0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
1b3e0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
1b3f0 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65  .  The legacy be
1b400 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
1b410 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1b420 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
1b430 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
1b440 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
1b450 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
1b460 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65  d you would have
1b470 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1b480 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1b490 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f  e3_reset()] in o
1b4a0 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20  rder.** to find 
1b4b0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1b4c0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1b4d0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1b4e0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1b4f0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1b500 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1b510 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1b520 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1b530 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1b540 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
1b550 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1b560 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32  [H13011] [H13012
1b570 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30  ] [H13013] [H130
1b580 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31  14] [H13015] [H1
1b590 33 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b  3016] [H13019] [
1b5a0 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e  H13021].**.*/.in
1b5b0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1b5c0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1b5d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1b5e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1b5f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1b600 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1b610 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1b620 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1b630 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1b640 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1b650 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1b660 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1b670 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1b680 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1b690 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1b6a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1b6b0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1b6c0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1b6d0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1b6e0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1b6f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1b700 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
1b710 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1b720 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1b730 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1b740 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1b750 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1b760 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1b770 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1b780 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1b790 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1b7a0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1b7b0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1b7c0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1b7d0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1b7e0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1b7f0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1b800 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1b810 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1b820 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1b830 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1b840 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
1b850 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1b860 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1b870 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1b880 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1b890 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1b8a0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1b8b0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1b8c0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1b8d0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1b8e0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1b8f0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1b900 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1b910 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1b920 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1b930 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1b940 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1b950 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1b960 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1b970 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1b980 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1b990 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
1b9a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1b9b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1b9c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1b9d0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1b9e0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1b9f0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1ba00 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1ba10 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1ba20 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1ba30 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1ba40 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1ba50 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1ba60 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1ba70 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1ba80 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1ba90 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1baa0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1bab0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1bac0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1bad0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
1bae0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20  g Statement SQL 
1baf0 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30  {H13100} <H13000
1bb00 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
1bb10 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
1bb20 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
1bb30 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
1bb40 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
1bb50 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
1bb60 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
1bb70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
1bb80 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1bb90 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
1bba0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1bbb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1bbc0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1bbd0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1bbe0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1bbf0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d  nts:.** [H13101]
1bc00 20 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30   [H13102] [H1310
1bc10 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  3].*/.const char
1bc20 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
1bc30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1bc40 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1bc50 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
1bc60 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
1bc70 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32  ect {H15000} <S2
1bc80 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
1bc90 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
1bca0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
1bcb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1bcc0 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
1bcd0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
1bce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1bcf0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
1bd00 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
1bd10 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
1bd20 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
1bd30 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
1bd40 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
1bd50 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
1bd60 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56  ues it stores. V
1bd70 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
1bd80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1bd90 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
1bda0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
1bdb0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
1bdc0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
1bdd0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
1bde0 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
1bdf0 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
1be00 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
1be10 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
1be20 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
1be30 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
1be40 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1be50 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
1be60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
1be70 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
1be80 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
1be90 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
1bea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1beb0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
1bec0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
1bed0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
1bee0 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
1bef0 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
1bf00 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
1bf10 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1bf20 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
1bf30 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
1bf40 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
1bf50 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
1bf60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
1bf70 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
1bf80 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20  ld.  A internal 
1bf90 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1bfa0 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
1bfb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1bfc0 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
1bfd0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1bfe0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
1bff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1c000 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
1c010 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
1c020 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
1c030 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
1c040 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1c050 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
1c060 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1c070 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
1c080 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
1c090 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
1c0a0 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
1c0b0 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
1c0c0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
1c0d0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
1c0e0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1c0f0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
1c100 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1c110 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
1c120 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1c130 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1c140 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1c150 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
1c160 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
1c170 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
1c180 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
1c190 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
1c1a0 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
1c1b0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
1c1c0 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
1c1d0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
1c1e0 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65  n between betwee
1c1f0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1c200 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1c210 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1c220 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
1c230 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
1c240 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
1c250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1c260 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
1c270 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
1c280 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
1c290 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1c2a0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
1c2b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1c2c0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
1c2d0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ted..** The sqli
1c2e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1c2f0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1c300 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1c310 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
1c320 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
1c330 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1c340 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
1c350 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
1c360 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
1c370 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
1c380 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
1c390 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
1c3a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
1c3b0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
1c3c0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
1c3d0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
1c3e0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
1c3f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1c400 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
1c410 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1c420 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
1c430 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
1c440 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
1c450 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
1c460 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32  t {H16001} <S202
1c470 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  00>.**.** The co
1c480 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
1c490 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
1c4a0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
1c4b0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
1c4c0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1c4d0 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  t.  A pointer to
1c4e0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
1c4f0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
1c500 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
1c510 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
1c520 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1c530 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
1c540 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1c550 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1c560 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
1c570 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
1c580 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
1c590 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
1c5a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c5b0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
1c5c0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
1c5d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
1c5e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
1c5f0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
1c600 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
1c610 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
1c620 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
1c630 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
1c640 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
1c650 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
1c660 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
1c670 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1c680 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
1c690 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
1c6a0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
1c6b0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
1c6c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
1c6d0 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30   {H13500} <S7030
1c6e0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1c6f0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
1c700 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1c710 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
1c720 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
1c730 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
1c740 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
1c750 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
1c760 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
1c770 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69   In the SQL stri
1c780 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ngs input to [sq
1c790 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c7a0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
1c7b0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
1c7c0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
1c7d0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
1c7e0 72 5d 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  r] in one of the
1c7f0 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20  se forms:.**.** 
1c800 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
1c810 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
1c820 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
1c830 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
1c840 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
1c850 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61  .**.** In the pa
1c860 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68  rameter forms sh
1c870 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73  own above NNN is
1c880 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
1c890 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
1c8a0 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65  is an alpha-nume
1c8b0 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ric parameter na
1c8c0 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f  me. The values o
1c8d0 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
1c8e0 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
1c8f0 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
1c900 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
1c910 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
1c920 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
1c930 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1c940 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1c950 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
1c960 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
1c970 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
1c980 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1c990 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
1c9a0 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
1c9b0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1c9c0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
1c9d0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
1c9e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1c9f0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
1ca00 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ants..**.** The 
1ca10 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1ca20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
1ca30 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
1ca40 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
1ca50 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
1ca60 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
1ca70 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57  n index of 1.  W
1ca80 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
1ca90 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
1caa0 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
1cab0 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
1cac0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
1cad0 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
1cae0 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
1caf0 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
1cb00 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
1cb10 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e   The index for n
1cb20 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
1cb30 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
1cb40 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
1cb50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1cb60 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
1cb70 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
1cb80 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
1cb90 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
1cba0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
1cbb0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e  of NNN..** The N
1cbc0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
1cbd0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
1cbe0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
1cbf0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
1cc00 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
1cc10 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
1cc20 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
1cc30 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   999)..**.** The
1cc40 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1cc50 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
1cc60 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
1cc70 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  meter..**.** In 
1cc80 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
1cc90 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
1cca0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
1ccb0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
1ccc0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1ccd0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
1cce0 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
1ccf0 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
1cd00 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
1cd10 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
1cd20 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
1cd30 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1cd40 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65  cters..** If the
1cd50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1cd60 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
1cd70 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
1cd80 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
1cd90 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1cda0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
1cdb0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
1cdc0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  r..**.** The fif
1cdd0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
1cde0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1cdf0 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
1ce00 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
1ce10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1ce20 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
1ce30 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
1ce40 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
1ce50 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
1ce60 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
1ce70 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
1ce80 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61  . If the fifth a
1ce90 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
1cea0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
1ceb0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
1cec0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
1ced0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
1cee0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1cef0 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
1cf00 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
1cf10 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1cf20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20  be freed..** If 
1cf30 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1cf40 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
1cf50 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
1cf60 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
1cf70 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
1cf80 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
1cf90 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
1cfa0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
1cfb0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
1cfc0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
1cfd0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  eturns..**.** Th
1cfe0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
1cff0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
1d000 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
1d010 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
1d020 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
1d030 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72  h zeroes.  A zer
1d040 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
1d050 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
1d060 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
1d070 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
1d080 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
1d090 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
1d0a0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
1d0b0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
1d0c0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
1d0d0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
1d0e0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
1d0f0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
1d100 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
1d110 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
1d120 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
1d130 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
1d140 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76  es..** A negativ
1d150 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
1d160 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
1d170 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
1d180 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68  h BLOB..**.** Th
1d190 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1d1a0 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  () routines must
1d1b0 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72   be called after
1d1c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1d1d0 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20  pare_v2()] (and 
1d1e0 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72  its variants) or
1d1f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1d200 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65  )] and.** before
1d210 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d220 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61  ]..** Bindings a
1d230 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
1d240 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
1d250 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
1d260 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61  .** Unbound para
1d270 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
1d280 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
1d290 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1d2a0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
1d2b0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
1d2c0 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63  ss or an error c
1d2d0 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69  ode if.** anythi
1d2e0 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20  ng goes wrong.  
1d2f0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
1d300 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
1d310 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
1d320 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
1d330 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e  ange.  [SQLITE_N
1d340 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
1d350 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
1d360 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ils..** [SQLITE_
1d370 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65  MISUSE] might be
1d380 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
1d390 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1d3a0 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76  called on a.** v
1d3b0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74  irtual machine t
1d3c0 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67  hat is the wrong
1d3d0 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20   state or which 
1d3e0 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e  has already been
1d3f0 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44   finalized..** D
1d400 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75  etection of misu
1d410 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65  se is unreliable
1d420 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
1d430 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e  should not depen
1d440 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d  d.** on SQLITE_M
1d450 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20  ISUSE returns.  
1d460 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73  SQLITE_MISUSE is
1d470 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64   intended to ind
1d480 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67  icate a.** a log
1d490 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20  ic error in the 
1d4a0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75  application.  Fu
1d4b0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1d4c0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
1d4d0 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 68   panic rather th
1d4e0 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  an return SQLITE
1d4f0 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53  _MISUSE..**.** S
1d500 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1d510 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1d520 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
1d530 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1d540 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1d550 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1d560 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1d570 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
1d580 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1d590 35 30 36 5d 20 5b 48 31 33 35 30 39 5d 20 5b 48  506] [H13509] [H
1d5a0 31 33 35 31 32 5d 20 5b 48 31 33 35 31 35 5d 20  13512] [H13515] 
1d5b0 5b 48 31 33 35 31 38 5d 20 5b 48 31 33 35 32 31  [H13518] [H13521
1d5c0 5d 20 5b 48 31 33 35 32 34 5d 20 5b 48 31 33 35  ] [H13524] [H135
1d5d0 32 37 5d 0a 2a 2a 20 5b 48 31 33 35 33 30 5d 20  27].** [H13530] 
1d5e0 5b 48 31 33 35 33 33 5d 20 5b 48 31 33 35 33 36  [H13533] [H13536
1d5f0 5d 20 5b 48 31 33 35 33 39 5d 20 5b 48 31 33 35  ] [H13539] [H135
1d600 34 32 5d 20 5b 48 31 33 35 34 35 5d 20 5b 48 31  42] [H13545] [H1
1d610 33 35 34 38 5d 20 5b 48 31 33 35 35 31 5d 0a 2a  3548] [H13551].*
1d620 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  *.*/.int sqlite3
1d630 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
1d640 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1d650 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
1d660 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
1d670 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1d680 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
1d690 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1d6a0 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
1d6b0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
1d6c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d6d0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
1d6e0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
1d6f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1d700 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
1d710 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1d720 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
1d730 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
1d740 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
1d750 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
1d760 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
1d770 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
1d780 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1d790 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1d7a0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
1d7b0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
1d7c0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
1d7d0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
1d7e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
1d7f0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
1d800 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
1d810 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
1d820 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
1d830 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
1d840 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
1d850 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
1d860 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
1d870 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48  QL Parameters {H
1d880 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13600} <S70300>.
1d890 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
1d8a0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
1d8b0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
1d8c0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
1d8d0 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
1d8e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d8f0 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
1d900 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
1d910 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
1d920 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
1d930 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
1d940 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
1d950 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
1d960 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
1d970 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
1d980 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
1d990 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
1d9a0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
1d9b0 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54  er time..**.** T
1d9c0 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
1d9d0 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
1d9e0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
1d9f0 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
1da00 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
1da10 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
1da20 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
1da30 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
1da40 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
1da50 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
1da60 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
1da70 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
1da80 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  N are used,.** t
1da90 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
1daa0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a   in the list..**
1dab0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1dac0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1dad0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1dae0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
1daf0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1db00 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
1db10 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1db20 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1db30 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1db40 73 3a 0a 2a 2a 20 5b 48 31 33 36 30 31 5d 0a 2a  s:.** [H13601].*
1db50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
1db60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1db70 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
1db80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1db90 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
1dba0 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31  st Parameter {H1
1dbb0 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3620} <S70300>.*
1dbc0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1dbd0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1dbe0 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20  ter to the name 
1dbf0 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b  of the n-th.** [
1dc00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
1dc10 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
1dc20 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c  atement]..** SQL
1dc30 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
1dc40 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
1dc50 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
1dc60 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
1dc70 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
1dc80 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
1dc90 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
1dca0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
1dcb0 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
1dcc0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
1dcd0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
1dce0 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
1dcf0 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
1dd00 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
1dd10 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
1dd20 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20  ..** Parameters 
1dd30 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
1dd40 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
1dd50 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
1dd60 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
1dd70 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65  are also referre
1dd80 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f  d to as "anonymo
1dd90 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
1dda0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1ddb0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
1ddc0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1ddd0 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49  , not 0..**.** I
1dde0 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73  f the value n is
1ddf0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
1de00 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72   if the n-th par
1de10 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
1de20 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
1de30 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
1de40 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1de50 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
1de60 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
1de70 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
1de80 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
1de90 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
1dea0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
1deb0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
1dec0 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
1ded0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1dee0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1def0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1df00 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1df10 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1df20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1df30 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1df40 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1df50 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1df60 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1df70 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1df80 73 3a 0a 2a 2a 20 5b 48 31 33 36 32 31 5d 0a 2a  s:.** [H13621].*
1df90 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1dfa0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1dfb0 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
1dfc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
1dfd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1dfe0 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
1dff0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
1e000 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20  n Name {H13640} 
1e010 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52  <S70300>.**.** R
1e020 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
1e030 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
1e040 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
1e050 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65  me.  The.** inde
1e060 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
1e070 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
1e080 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
1e090 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
1e0a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
1e0b0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1e0c0 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a  nd()].  A zero.*
1e0d0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
1e0e0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
1e0f0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
1e100 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a    The parameter.
1e110 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
1e120 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
1e130 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
1e140 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
1e150 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
1e160 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
1e170 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1e180 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1e190 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1e1a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1e1b0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1e1c0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1e1d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1e1e0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
1e1f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1e200 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1e210 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1e220 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 34 31 5d  nts:.** [H13641]
1e230 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e240 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1e250 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
1e260 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
1e270 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
1e280 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
1e290 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
1e2a0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
1e2b0 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37  ent {H13660} <S7
1e2c0 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74  0300>.**.** Cont
1e2d0 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
1e2e0 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
1e2f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1e300 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
1e310 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
1e320 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
1e330 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
1e340 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1e350 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75  .** Use this rou
1e360 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
1e370 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
1e380 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  s to NULL..**.**
1e390 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1e3a0 2a 20 5b 48 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e  * [H13661].*/.in
1e3b0 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
1e3c0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
1e3d0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
1e3e0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
1e3f0 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
1e400 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33   Result Set {H13
1e410 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  710} <S10700>.**
1e420 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e  .** Return the n
1e430 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1e440 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
1e450 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
1e460 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
1e470 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73  statement]. This
1e480 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1e490 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
1e4a0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
1e4b0 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
1e4c0 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
1e4d0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
1e4e0 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65  DATE])..**.** Re
1e4f0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1e500 48 31 33 37 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73  H13711].*/.int s
1e510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
1e520 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
1e530 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1e540 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
1e550 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
1e560 75 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d  ult Set {H13720}
1e570 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
1e580 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1e590 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
1e5a0 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
1e5b0 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
1e5c0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
1e5d0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
1e5e0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  ] statement.  Th
1e5f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
1e600 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
1e610 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
1e620 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
1e630 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1e640 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
1e650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1e660 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
1e670 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
1e680 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1e690 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
1e6a0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
1e6b0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
1e6c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e6d0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
1e6e0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
1e6f0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65  ] statement. The
1e700 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1e710 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
1e720 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  mn number.  The 
1e730 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
1e740 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
1e750 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
1e760 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
1e770 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
1e780 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
1e790 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
1e7a0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
1e7b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1e7c0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
1e7d0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
1e7e0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
1e7f0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
1e800 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1e810 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
1e820 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  column..**.** If
1e830 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e840 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
1e850 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
1e860 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
1e870 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
1e880 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
1e890 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
1e8a0 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
1e8b0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1e8c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1e8d0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
1e8e0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
1e8f0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
1e900 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
1e910 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
1e920 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
1e930 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
1e940 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
1e950 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
1e960 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1e970 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
1e980 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
1e990 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
1e9a0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
1e9b0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
1e9c0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1e9d0 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 32 31 5d 20  ts:.** [H13721] 
1e9e0 5b 48 31 33 37 32 33 5d 20 5b 48 31 33 37 32 34  [H13723] [H13724
1e9f0 5d 20 5b 48 31 33 37 32 35 5d 20 5b 48 31 33 37  ] [H13725] [H137
1ea00 32 36 5d 20 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a  26] [H13727].*/.
1ea10 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1ea20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1ea30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1ea40 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
1ea50 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
1ea60 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
1ea70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
1ea80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ea90 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
1eaa0 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
1eab0 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37  t {H13740} <S107
1eac0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
1ead0 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
1eae0 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
1eaf0 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d  rmine what colum
1eb00 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62  n of what.** tab
1eb10 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61  le in which data
1eb20 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66  base a result of
1eb30 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
1eb40 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d  ement comes from
1eb50 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  ..** The name of
1eb60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
1eb70 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
1eb80 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
1eb90 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
1eba0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
1ebb0 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61  string.  The _da
1ebc0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
1ebd0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
1ebe0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
1ebf0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
1ec00 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
1ec10 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
1ec20 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
1ec30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
1ec40 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
1ec50 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
1ec60 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
1ec70 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
1ec80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
1ec90 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
1eca0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1ecb0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
1ecc0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
1ecd0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
1ece0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
1ecf0 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
1ed00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ing..**.** The n
1ed10 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
1ed20 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
1ed30 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
1ed40 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
1ed50 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
1ed60 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  olumn..**.** The
1ed70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1ed80 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  to the following
1ed90 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65   calls is a [pre
1eda0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1edb0 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  ..** These funct
1edc0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
1edd0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
1ede0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
1edf0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
1ee00 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
1ee10 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
1ee20 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
1ee30 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  nt..**.** If the
1ee40 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
1ee50 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
1ee60 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
1ee70 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
1ee80 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
1ee90 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
1eea0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
1eeb0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
1eec0 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68  urn.** NULL.  Th
1eed0 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
1eee0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
1eef0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
1ef00 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
1ef10 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65  ** occurs.  Othe
1ef20 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
1ef30 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
1ef40 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
1ef50 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61  base, table.** a
1ef60 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  nd column that q
1ef70 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
1ef80 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
1ef90 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20   from..**.** As 
1efa0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
1efb0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
1efc0 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68  e postfixed with
1efd0 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
1efe0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
1eff0 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65  trings, the othe
1f000 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
1f010 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a  rn UTF-8. {END}.
1f020 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73  **.** These APIs
1f030 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
1f040 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
1f050 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
1f060 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
1f070 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
1f080 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
1f090 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
1f0a0 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  l defined..**.**
1f0b0 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20   {A13751}.** If 
1f0c0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
1f0d0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
1f0e0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
1f0f0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
1f100 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
1f110 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
1f120 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
1f130 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
1f140 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
1f150 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
1f160 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1f170 0a 2a 2a 20 5b 48 31 33 37 34 31 5d 20 5b 48 31  .** [H13741] [H1
1f180 33 37 34 32 5d 20 5b 48 31 33 37 34 33 5d 20 5b  3742] [H13743] [
1f190 48 31 33 37 34 34 5d 20 5b 48 31 33 37 34 35 5d  H13744] [H13745]
1f1a0 20 5b 48 31 33 37 34 36 5d 20 5b 48 31 33 37 34   [H13746] [H1374
1f1b0 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  8].**.** If two 
1f1c0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
1f1d0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
1f1e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
1f1f0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
1f200 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
1f210 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
1f220 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
1f230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f240 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
1f250 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
1f260 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
1f270 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
1f280 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
1f290 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1f2a0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
1f2b0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
1f2c0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
1f2d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1f2e0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
1f2f0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
1f300 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
1f310 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1f320 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
1f330 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1f340 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
1f350 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1f360 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
1f370 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1f380 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1f390 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
1f3a0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
1f3b0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
1f3c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1f3d0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
1f3e0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
1f3f0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
1f400 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
1f410 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
1f420 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31  Query Result {H1
1f430 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3760} <S10700>.*
1f440 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
1f450 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
1f460 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f470 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
1f480 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
1f490 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1f4a0 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
1f4b0 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
1f4c0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
1f4d0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
1f4e0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
1f4f0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
1f500 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
1f510 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
1f520 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
1f530 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
1f540 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
1f550 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63  d.  If the Nth c
1f560 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
1f570 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
1f580 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
1f590 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
1f5a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
1f5b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
1f5c0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1f5d0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
1f5e0 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a   encoded. {END}.
1f5f0 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
1f600 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
1f610 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
1f620 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
1f630 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
1f640 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
1f650 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
1f660 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
1f670 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
1f680 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
1f690 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
1f6a0 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
1f6b0 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
1f6c0 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
1f6d0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
1f6e0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
1f6f0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
1f700 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
1f710 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
1f720 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  (i==0)..**.** SQ
1f730 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
1f740 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
1f750 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61  g.  So just beca
1f760 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
1f770 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
1f780 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
1f790 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
1f7a0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
1f7b0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
1f7c0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
1f7d0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
1f7e0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
1f7f0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
1f800 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
1f810 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
1f820 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65  ot static.  Type
1f830 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
1f840 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
1f850 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
1f860 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
1f870 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
1f880 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
1f890 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1f8a0 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 36 31 5d 20  ts:.** [H13761] 
1f8b0 5b 48 31 33 37 36 32 5d 20 5b 48 31 33 37 36 33  [H13762] [H13763
1f8c0 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ].*/.const char 
1f8d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1f8e0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
1f8f0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
1f900 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1f910 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
1f920 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1f930 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
1f940 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
1f950 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1f960 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30  t {H13200} <S100
1f970 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  00>.**.** After 
1f980 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1f990 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
1f9a0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
1f9b0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
1f9c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f9d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
1f9e0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
1f9f0 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
1fa00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
1fa10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1fa20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
1fa30 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
1fa40 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
1fa50 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
1fa60 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
1fa70 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
1fa80 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
1fa90 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
1faa0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
1fab0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
1fac0 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
1fad0 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
1fae0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
1faf0 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
1fb00 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
1fb10 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
1fb20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fb30 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1fb40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1fb50 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
1fb60 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
1fb70 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
1fb80 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
1fb90 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1fba0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
1fbb0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
1fbc0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
1fbd0 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
1fbe0 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
1fbf0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
1fc00 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
1fc10 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
1fc20 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  orted..**.** In 
1fc30 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
1fc40 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
1fc50 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
1fc60 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
1fc70 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
1fc80 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
1fc90 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
1fca0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
1fcb0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68  MISUSE]..** With
1fcc0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1fcd0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
1fce0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
1fcf0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
1fd00 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1fd10 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
1fd20 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
1fd30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1fd40 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
1fd50 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
1fd60 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
1fd70 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
1fd80 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
1fd90 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
1fda0 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61  job.  If the sta
1fdb0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
1fdc0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
1fdd0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
1fde0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
1fdf0 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
1fe00 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
1fe10 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
1fe20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1fe30 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
1fe40 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
1fe50 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
1fe60 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
1fe70 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
1fe80 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
1fe90 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
1fea0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
1feb0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
1fec0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
1fed0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
1fee0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
1fef0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
1ff00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
1ff10 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
1ff20 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
1ff30 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
1ff40 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
1ff50 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
1ff60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
1ff70 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
1ff80 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
1ff90 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
1ffa0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
1ffb0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1ffc0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
1ffd0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
1ffe0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
1fff0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
20000 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
20010 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
20020 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
20030 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
20040 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
20050 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
20060 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
20070 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
20080 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
20090 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
200a0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
200b0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
200c0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
200d0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  *.** [SQLITE_ERR
200e0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
200f0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
20100 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
20110 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
20120 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
20130 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
20140 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
20150 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
20160 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
20170 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
20180 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
20190 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
201a0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20  msg()]..** With 
201b0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
201c0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
201d0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
201e0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
201f0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
20200 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
20210 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
20220 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
20230 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
20240 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
20250 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
20260 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
20270 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20280 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
20290 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
202a0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
202b0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
202c0 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
202d0 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
202e0 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
202f0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
20300 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
20310 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
20320 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
20330 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
20340 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
20350 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
20360 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
20370 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
20380 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
20390 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
203a0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
203b0 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
203c0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
203d0 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
203e0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
203f0 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
20400 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
20410 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
20420 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
20430 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
20440 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
20450 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
20460 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
20470 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
20480 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
20490 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
204a0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
204b0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
204c0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
204d0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
204e0 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
204f0 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
20500 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
20510 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
20520 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
20530 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
20540 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
20550 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
20560 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
20570 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
20580 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
20590 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
205a0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
205b0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
205c0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
205d0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
205e0 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
205f0 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
20600 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
20610 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
20620 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
20630 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
20640 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
20650 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
20660 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
20670 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20680 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20690 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
206a0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
206b0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
206c0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
206d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
206e0 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
206f0 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
20700 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
20710 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
20720 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
20730 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
20740 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
20750 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
20760 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
20770 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  nded..**.** Requ
20780 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
20790 33 32 30 32 5d 20 5b 48 31 35 33 30 34 5d 20 5b  3202] [H15304] [
207a0 48 31 35 33 30 36 5d 20 5b 48 31 35 33 30 38 5d  H15306] [H15308]
207b0 20 5b 48 31 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74   [H15310].*/.int
207c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
207d0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
207e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
207f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
20800 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
20810 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30   {H13770} <S1070
20820 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73  0>.**.** Returns
20830 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76   the number of v
20840 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72  alues in the cur
20850 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
20860 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a  result set..**.*
20870 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
20880 2a 2a 20 5b 48 31 33 37 37 31 5d 20 5b 48 31 33  ** [H13771] [H13
20890 37 37 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  772].*/.int sqli
208a0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
208b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
208c0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
208d0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
208e0 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 30  l Datatypes {H10
208f0 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31  265} <S10110><S1
20900 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0120>.** KEYWORD
20910 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
20920 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76  *.** {H10266} Ev
20930 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
20940 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
20950 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
20960 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
20970 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
20980 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
20990 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
209a0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
209b0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
209c0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
209d0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
209e0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20  > NULL.** </ul> 
209f0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
20a00 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
20a10 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
20a20 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
20a30 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
20a40 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
20a50 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
20a60 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
20a70 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
20a80 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
20a90 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
20aa0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
20ab0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
20ac0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
20ad0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
20ae0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
20af0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
20b00 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
20b10 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
20b20 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
20b30 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
20b40 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
20b50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
20b60 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
20b70 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
20b80 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
20b90 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
20ba0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
20bb0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
20bc0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
20bd0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
20be0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
20bf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
20c00 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
20c10 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 30  m A Query {H1380
20c20 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b  0} <S10700>.** K
20c30 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
20c40 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
20c50 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
20c60 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
20c70 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65   "result set que
20c80 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ry" interface..*
20c90 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
20ca0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
20cb0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
20cc0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
20cd0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
20ce0 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
20cf0 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20  uery.  In every 
20d00 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
20d10 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
20d20 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
20d30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20d40 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
20d50 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
20d60 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
20d70 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
20d80 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
20d90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20da0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
20db0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
20dc0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
20dd0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
20de0 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
20df0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
20e00 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
20e10 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  be returned.  Th
20e20 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
20e30 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
20e40 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
20e50 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  x 0..**.** If th
20e60 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
20e70 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
20e80 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
20e90 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
20ea0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
20eb0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
20ec0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
20ed0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
20ee0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
20ef0 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
20f00 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
20f10 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
20f20 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
20f30 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
20f40 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
20f50 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
20f60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
20f70 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
20f80 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
20f90 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
20fa0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
20fb0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
20fc0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
20fd0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
20fe0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
20ff0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
21000 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
21010 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
21020 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
21030 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
21040 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
21050 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
21060 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
21070 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
21080 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
21090 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
210a0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
210b0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
210c0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
210d0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
210e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
210f0 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
21100 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
21110 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
21120 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21130 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
21140 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
21150 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
21160 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
21170 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
21180 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
21190 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
211a0 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65   column.  The re
211b0 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
211c0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
211d0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
211e0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
211f0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
21200 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
21210 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
21220 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
21230 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
21240 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
21250 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
21260 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
21270 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
21280 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
21290 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
212a0 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
212b0 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
212c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
212d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
212e0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
212f0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
21300 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
21310 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
21320 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
21330 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
21340 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
21350 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
21360 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  .**.** If the re
21370 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
21380 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
21390 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
213a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
213b0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
213c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
213d0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
213e0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
213f0 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
21400 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
21410 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
21420 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
21430 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
21440 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
21450 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
21460 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
21470 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  tes..** If the r
21480 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
21490 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
214a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
214b0 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
214c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
214d0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
214e0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
214f0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
21500 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
21510 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
21520 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
21530 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
21540 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
21550 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
21560 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
21570 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
21580 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74  ing.  For clarit
21590 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  y: the value ret
215a0 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d  urned is the num
215b0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
215c0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
215d0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
215e0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
215f0 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72  ** Strings retur
21600 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
21610 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
21620 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
21630 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
21640 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
21650 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
21660 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68   terminated.  Th
21670 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
21680 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
21690 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
216a0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
216b0 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72  LOB is an arbitr
216c0 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ary.** pointer, 
216d0 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20  possibly even a 
216e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
216f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21700 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
21710 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
21720 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lar to sqlite3_c
21730 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
21740 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20   but leaves the 
21750 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36  result in UTF-16
21760 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
21770 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
21780 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a   UTF-8..** The z
21790 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
217a0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
217b0 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
217c0 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72  .** The object r
217d0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
217e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
217f0 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
21800 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
21810 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
21820 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
21830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
21840 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
21850 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
21860 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
21870 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
21880 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
21890 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
218a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
218b0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
218c0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
218d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
218e0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
218f0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
21900 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
21910 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
21920 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
21930 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
21940 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
21950 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
21960 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
21970 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
21980 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
21990 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
219a0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
219b0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
219c0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
219d0 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a  ropriate.  For.*
219e0 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
219f0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
21a00 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
21a10 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
21a20 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
21a30 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
21a40 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
21a50 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
21a60 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
21a70 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
21a80 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66  atically.  The f
21a90 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
21aa0 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
21ab0 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
21ac0 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
21ad0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
21ae0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
21af0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
21b00 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
21b10 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
21b20 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
21b30 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
21b40 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
21b50 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
21b60 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
21b70 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
21b80 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
21b90 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
21ba0 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
21bb0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
21bc0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
21bd0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
21be0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
21bf0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
21c00 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
21c10 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
21c20 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
21c30 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
21c40 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
21c50 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
21c60 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
21c70 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
21c80 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
21c90 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
21ca0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
21cb0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
21cc0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
21cd0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
21ce0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
21cf0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
21d00 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
21d10 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
21d20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
21d30 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
21d40 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
21d50 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
21d60 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
21d70 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
21d80 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
21d90 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
21da0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
21db0 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
21dc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
21dd0 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
21de0 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
21df0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
21e00 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
21e10 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
21e20 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
21e30 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
21e40 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
21e50 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
21e60 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
21e70 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
21e80 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
21e90 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
21ea0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
21eb0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
21ec0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
21ed0 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
21ee0 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
21ef0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
21f00 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
21f10 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
21f20 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
21f30 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
21f40 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
21f50 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  te>.**.** The ta
21f60 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
21f70 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
21f80 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
21f90 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
21fa0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
21fb0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
21fc0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
21fd0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
21fe0 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
21ff0 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
22000 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
22010 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
22020 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
22030 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
22040 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
22050 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
22060 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
22070 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
22080 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
22090 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
220a0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
220b0 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
220c0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
220d0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
220e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
220f0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
22100 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
22110 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
22120 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
22130 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
22140 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
22150 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
22160 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
22170 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
22180 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
22190 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
221a0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
221b0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
221c0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
221d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
221e0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
221f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
22200 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
22210 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
22220 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
22230 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
22240 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
22250 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
22260 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
22270 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
22280 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
22290 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
222a0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
222b0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
222c0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
222d0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
222e0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
222f0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
22300 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
22310 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
22320 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
22330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
22340 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
22350 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22360 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
22370 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
22380 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
22390 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
223a0 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
223b0 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f  .**.** Conversio
223c0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
223d0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
223e0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
223f0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
22400 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
22410 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
22420 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
22430 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
22440 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
22450 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
22460 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20   pointer points 
22470 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  to will have bee
22480 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
22490 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
224a0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
224b0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
224c0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
224d0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
224e0 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
224f0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
22500 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
22510 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
22520 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
22530 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
22540 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
22550 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
22560 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
22570 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
22580 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
22590 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
225a0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
225b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
225c0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
225d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
225e0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
225f0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
22600 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
22610 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
22620 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
22630 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
22640 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
22650 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
22660 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
22670 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
22680 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
22690 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
226a0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
226b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
226c0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
226d0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
226e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
226f0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
22700 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
22710 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
22720 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
22730 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
22740 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
22750 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
22760 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
22770 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
22780 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
22790 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
227a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
227b0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
227c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
227d0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
227e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
227f0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
22800 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
22810 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
22820 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
22830 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
22840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
22850 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tes()..**.** The
22860 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
22870 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
22880 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
22890 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
228a0 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
228b0 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
228c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
228d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
228e0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
228f0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
22900 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d  called.  The mem
22910 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
22920 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
22930 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
22940 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
22950 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
22960 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
22970 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
22980 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22990 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
229a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
229b0 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
229c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
229d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d  ..**.** If a mem
229e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
229f0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
22a00 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
22a10 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
22a20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
22a30 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
22a40 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
22a50 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
22a60 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
22a70 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
22a80 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
22a90 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
22aa0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
22ab0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
22ac0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
22ad0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
22ae0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
22af0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  NOMEM]..**.** Re
22b00 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
22b10 48 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36 5d  H13803] [H13806]
22b20 20 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38 31   [H13809] [H1381
22b30 32 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 33  2] [H13815] [H13
22b40 38 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48  818] [H13821] [H
22b50 31 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32  13824].** [H1382
22b60 37 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 63  7] [H13830].*/.c
22b70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
22b80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
22b90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22ba0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
22bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
22bc0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
22bd0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
22be0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22bf0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
22c00 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
22c10 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
22c20 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
22c30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
22c40 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
22c50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
22c60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22c70 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
22c80 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
22c90 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
22ca0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
22cb0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
22cc0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
22cd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
22ce0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22cf0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
22d00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
22d10 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
22d20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
22d30 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
22d40 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
22d50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
22d60 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
22d70 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
22d80 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
22d90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
22da0 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
22db0 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
22dc0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
22dd0 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30  nt Object {H1330
22de0 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31  0} <S70300><S301
22df0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
22e00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22e10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
22e20 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
22e30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22e40 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ent]..** If the 
22e50 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78  statement was ex
22e60 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75  ecuted successfu
22e70 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  lly or not execu
22e80 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
22e90 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  .** SQLITE_OK is
22ea0 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78   returned. If ex
22eb0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  ecution of the s
22ec0 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20  tatement failed 
22ed0 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  then an.** [erro
22ee0 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  r code] or [exte
22ef0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
22f00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
22f10 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
22f20 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
22f30 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
22f40 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
22f50 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   of the.** [prep
22f60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
22f70 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c    If the virtual
22f80 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74   machine has not
22f90 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
22fa0 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69  ecution when thi
22fb0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  s routine is cal
22fc0 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b  led, that is lik
22fd0 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e  e.** encounterin
22fe0 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e  g an error or an
22ff0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
23000 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
23010 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20  ..** Incomplete 
23020 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72  updates may be r
23030 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74  olled back and t
23040 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63  ransactions canc
23050 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  eled,.** dependi
23060 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
23070 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
23080 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
23090 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
230a0 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
230b0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
230c0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32  ents:.** [H11302
230d0 5d 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e  ] [H11304].*/.in
230e0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
230f0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
23100 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
23110 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
23120 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
23130 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
23140 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  330} <S70300>.**
23150 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23160 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
23170 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
23180 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
23190 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
231a0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
231b0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
231c0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
231d0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
231e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
231f0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
23200 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
23210 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
23220 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
23230 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
23240 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
23250 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
23260 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
23270 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
23280 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
23290 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
232a0 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b  * {H11332} The [
232b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
232c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
232d0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
232e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
232f0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
23300 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
23310 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
23320 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49  **.** {H11334} I
23330 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
23340 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
23350 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
23360 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
23370 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23380 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
23390 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
233a0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
233b0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
233c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
233d0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
233e0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
233f0 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  on S,.**        
23400 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
23410 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
23420 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
23430 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66  *.** {H11336} If
23440 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23450 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
23460 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
23470 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
23480 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23490 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
234a0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
234b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
234c0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
234d0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
234e0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
234f0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38  ]..**.** {H11338
23500 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
23510 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
23520 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
23530 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
23540 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79            of any
23550 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
23560 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
23570 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23580 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
23590 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
235a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
235b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
235c0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
235d0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
235e0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30  Functions {H1610
235f0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b  0} <S20200>.** K
23600 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
23610 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
23620 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
23630 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
23640 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
23650 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
23660 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
23670 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
23680 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
23690 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  se two functions
236a0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
236b0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
236c0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
236d0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
236e0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
236f0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
23700 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
23710 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
23720 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
23730 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
23740 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
23750 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
23760 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a  e between the.**
23770 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65   two is that the
23780 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
23790 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r, the name of t
237a0 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63  he (scalar) func
237b0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
237c0 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64  gate, is encoded
237d0 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71   in UTF-8 for sq
237e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
237f0 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d  ction() and UTF-
23800 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  16.** for sqlite
23810 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
23820 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
23830 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
23840 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
23850 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
23860 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
23870 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
23880 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61   be added.  If a
23890 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20   single program 
238a0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
238b0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
238c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e  onnection intern
238d0 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66  ally, then SQL f
238e0 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
238f0 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61   added individua
23900 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64  lly to.** each d
23910 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23920 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  on..**.** The se
23930 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
23940 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
23950 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
23960 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
23970 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54  ** redefined.  T
23980 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
23990 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
239a0 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65   to 255 bytes, e
239b0 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74  xclusive of.** t
239c0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
239d0 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
239e0 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
239f0 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
23a00 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
23a10 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  ers.  Any attemp
23a20 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
23a30 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
23a40 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
23a50 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
23a60 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67  ITE_ERROR] being
23a70 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
23a80 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
23a90 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
23aa0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
23ab0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
23ac0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
23ad0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
23ae0 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70  takes. If this p
23af0 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
23b00 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
23b10 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
23b20 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
23b30 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
23b40 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
23b50 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
23b60 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
23b70 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
23b80 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
23b90 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
23ba0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
23bb0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
23bc0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
23bd0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
23be0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
23bf0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
23c00 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
23c10 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
23c20 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
23c30 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
23c40 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
23c50 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
23c60 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
23c70 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
23c80 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   Any SQL functio
23c90 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
23ca0 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20   should be able 
23cb0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20  to work.** work 
23cc0 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
23cd0 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
23ce0 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
23cf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
23d00 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
23d10 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
23d20 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
23d30 74 68 65 72 2e 20 20 41 6e 20 61 70 70 6c 69 63  ther.  An applic
23d40 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
23d50 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
23d60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
23d70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
23d80 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
23d90 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
23da0 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
23db0 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
23dc0 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
23dd0 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
23de0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
23df0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
23e00 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
23e10 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
23e20 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
23e30 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
23e40 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
23e50 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
23e60 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
23e70 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
23e80 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
23e90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
23ea0 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
23eb0 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
23ec0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
23ed0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
23ee0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
23ef0 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
23f00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
23f10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
23f20 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
23f30 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
23f40 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
23f50 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
23f60 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
23f70 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
23f80 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
23f90 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ata()]..**.** Th
23fa0 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
23fb0 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
23fc0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
23fd0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
23fe0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
23ff0 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
24000 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
24010 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
24020 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
24030 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c  ggregate. A scal
24040 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
24050 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
24060 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
24070 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
24080 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70  ack only, NULL p
24090 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
240a0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
240b0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
240c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
240d0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
240e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
240f0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
24100 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
24110 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
24120 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
24130 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
24140 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78   To delete an ex
24150 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
24160 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
24170 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
24180 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
24190 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e  ction callbacks.
241a0 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72  .**.** It is per
241b0 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
241c0 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
241d0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
241e0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
241f0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
24200 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
24210 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
24220 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
24230 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
24240 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
24250 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
24260 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73    SQLite will us
24270 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
24280 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
24290 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
242a0 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
242b0 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
242c0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
242d0 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   A function impl
242e0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
242f0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
24300 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
24310 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
24320 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
24330 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
24340 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
24350 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75  tive nArg.  A fu
24360 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
24370 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
24380 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
24390 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
243a0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
243b0 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
243c0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
243d0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
243e0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
243f0 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20   .** A function 
24400 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
24410 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
24420 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
24430 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
24440 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
24450 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
24460 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
24470 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
24480 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
24490 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
244a0 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e  .** Built-in fun
244b0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
244c0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
244d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
244e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
244f0 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70 6c  * The first appl
24500 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
24510 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
24520 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72  given name overr
24530 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c  ides all.** buil
24540 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69  t-in functions i
24550 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
24560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
24570 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
24580 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  ame..** Subseque
24590 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  nt application-d
245a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
245b0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   of the same nam
245c0 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20  e only override 
245d0 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63  .** prior applic
245e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
245f0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  nctions that are
24600 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20   an exact match 
24610 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  for the.** numbe
24620 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
24630 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e  and preferred en
24640 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e  coding..**.** An
24650 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
24660 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
24670 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
24680 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
24690 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
246a0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
246b0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
246c0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
246d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
246e0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
246f0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
24700 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
24710 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
24720 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
24730 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
24740 74 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d 20  ts:.** [H16103] 
24750 5b 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30 39  [H16106] [H16109
24760 5d 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36 31  ] [H16112] [H161
24770 31 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48 31  18] [H16121] [H1
24780 36 31 32 37 5d 0a 2a 2a 20 5b 48 31 36 31 33 30  6127].** [H16130
24790 5d 20 5b 48 31 36 31 33 33 5d 20 5b 48 31 36 31  ] [H16133] [H161
247a0 33 36 5d 20 5b 48 31 36 31 33 39 5d 20 5b 48 31  36] [H16139] [H1
247b0 36 31 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6142].*/.int sql
247c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
247d0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
247e0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
247f0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
24800 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
24810 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
24820 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
24830 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
24840 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
24850 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
24860 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
24870 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
24880 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
24890 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
248a0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
248b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
248c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
248d0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
248e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
248f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
24900 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
24910 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
24920 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
24930 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
24940 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
24950 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
24960 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
24970 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
24980 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
24990 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
249a0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
249b0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
249c0 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
249d0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
249e0 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37  ncodings {H10267
249f0 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31  } <S50200> <H161
24a00 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
24a10 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
24a20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
24a30 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
24a40 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
24a50 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
24a60 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
24a70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24a80 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
24a90 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
24aa0 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
24ab0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
24ac0 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
24ad0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
24ae0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
24af0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
24b00 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
24b10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24b20 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
24b30 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
24b40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
24b50 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
24b60 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
24b70 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
24b80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
24b90 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
24ba0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24bb0 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
24bc0 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
24bd0 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
24be0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
24bf0 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
24c00 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
24c10 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
24c20 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
24c30 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
24c40 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
24c50 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
24c60 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
24c70 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
24c80 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
24c90 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
24ca0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
24cb0 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
24cc0 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
24cd0 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
24ce0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
24cf0 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
24d00 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74  to tell you what
24d10 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
24d20 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
24d30 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
24d40 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
24d50 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
24d60 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
24d70 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
24d80 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
24d90 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
24da0 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
24db0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
24dc0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
24dd0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
24de0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
24df0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
24e00 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
24e10 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
24e20 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
24e30 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
24e40 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
24e50 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
24e60 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
24e70 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
24e80 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
24e90 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
24ea0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
24eb0 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
24ec0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
24ed0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
24ee0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
24ef0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
24f00 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31  meter Values {H1
24f10 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  5100} <S20200>.*
24f20 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
24f30 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
24f40 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
24f50 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
24f60 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
24f70 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
24f80 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
24f90 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
24fa0 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
24fb0 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
24fc0 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
24fd0 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
24fe0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
24ff0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
25000 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
25010 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
25020 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25030 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
25040 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25050 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
25060 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
25070 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
25080 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
25090 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
250a0 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
250b0 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
250c0 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
250d0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
250e0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
250f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25100 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
25110 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
25120 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
25130 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
25140 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
25150 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
25160 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
25170 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
25180 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
25190 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
251a0 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
251b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
251c0 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
251d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
251e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
251f0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
25200 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
25210 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
25220 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25230 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
25240 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
25250 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
25260 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
25270 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
25280 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
25290 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
252a0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
252b0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
252c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
252d0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
252e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
252f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
25300 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
25310 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
25320 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
25330 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
25340 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
25350 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
25360 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
25370 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
25380 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
25390 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
253a0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
253b0 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
253c0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
253d0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
253e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
253f0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
25400 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
25410 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
25420 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
25430 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
25440 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
25450 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25460 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
25470 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
25480 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
25490 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
254a0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
254b0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
254c0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
254d0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
254e0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
254f0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
25500 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
25510 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
25520 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
25530 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
25540 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
25550 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
25560 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
25570 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
25580 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
25590 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
255a0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
255b0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
255c0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
255d0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
255e0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
255f0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
25600 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
25610 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
25620 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
25630 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
25640 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
25650 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
25660 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
25670 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
25680 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
25690 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
256a0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
256b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
256c0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
256d0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
256e0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
256f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
25700 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
25710 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
25720 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
25730 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
25740 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
25750 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
25760 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
25770 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
25780 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
25790 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
257a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
257b0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
257c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
257d0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  ] parameters..**
257e0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
257f0 3a 0a 2a 2a 20 5b 48 31 35 31 30 33 5d 20 5b 48  :.** [H15103] [H
25800 31 35 31 30 36 5d 20 5b 48 31 35 31 30 39 5d 20  15106] [H15109] 
25810 5b 48 31 35 31 31 32 5d 20 5b 48 31 35 31 31 35  [H15112] [H15115
25820 5d 20 5b 48 31 35 31 31 38 5d 20 5b 48 31 35 31  ] [H15118] [H151
25830 32 31 5d 20 5b 48 31 35 31 32 34 5d 0a 2a 2a 20  21] [H15124].** 
25840 5b 48 31 35 31 32 37 5d 20 5b 48 31 35 31 33 30  [H15127] [H15130
25850 5d 20 5b 48 31 35 31 33 33 5d 20 5b 48 31 35 31  ] [H15133] [H151
25860 33 36 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  36].*/.const voi
25870 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
25880 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
25890 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
258a0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
258b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
258c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
258d0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
258e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
258f0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
25900 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
25910 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
25920 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
25930 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
25940 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
25950 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
25960 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
25970 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
25980 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
25990 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
259a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
259b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
259c0 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
259d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
259e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
259f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
25a00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
25a10 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
25a20 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
25a30 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
25a40 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
25a50 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
25a60 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
25a70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
25a80 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
25a90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
25aa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
25ab0 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
25ac0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
25ad0 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30  {H16210} <S20200
25ae0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  >.**.** The impl
25af0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
25b00 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
25b10 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
25b20 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
25b30 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
25b40 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
25b50 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
25b60 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
25b70 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
25b80 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
25b90 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
25ba0 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69  d for a.** parti
25bb0 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
25bc0 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
25bd0 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
25be0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
25bf0 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61  hat.** memory, a
25c00 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
25c10 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73  nter to it. On s
25c20 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
25c30 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
25c40 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
25c50 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
25c60 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
25c70 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
25c80 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ex,.** the same 
25c90 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
25ca0 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ed. The implemen
25cb0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67  tation of the ag
25cc0 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a  gregate can use.
25cd0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  ** the returned 
25ce0 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
25cf0 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
25d00 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
25d10 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
25d20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
25d30 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
25d40 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
25d50 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
25d60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
25d70 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
25d80 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
25d90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
25da0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
25db0 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
25dc0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
25dd0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
25de0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
25df0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
25e00 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
25e10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
25e20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
25e30 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
25e40 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
25e50 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
25e60 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
25e70 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
25e80 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
25e90 73 3a 0a 2a 2a 20 5b 48 31 36 32 31 31 5d 20 5b  s:.** [H16211] [
25ea0 48 31 36 32 31 33 5d 20 5b 48 31 36 32 31 35 5d  H16213] [H16215]
25eb0 20 5b 48 31 36 32 31 37 5d 0a 2a 2f 0a 76 6f 69   [H16217].*/.voi
25ec0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
25ed0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
25ee0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
25ef0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
25f00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
25f10 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
25f20 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53  ions {H16240} <S
25f30 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
25f40 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
25f50 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
25f60 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
25f70 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
25f80 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
25f90 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
25fa0 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
25fb0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
25fc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25fd0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
25fe0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
25ff0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
26000 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
26010 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
26020 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
26030 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
26040 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a  unction. {END}.*
26050 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
26060 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
26070 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
26080 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
26090 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
260a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
260b0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
260c0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
260d0 73 3a 0a 2a 2a 20 5b 48 31 36 32 34 33 5d 0a 2a  s:.** [H16243].*
260e0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
260f0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
26100 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
26110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
26120 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
26130 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  n For Functions 
26140 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30 30  {H16250} <S60600
26150 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S20200>.**.** 
26160 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
26170 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
26180 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26190 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
261a0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
261b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
261c0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
261d0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
261e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
261f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
26200 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
26210 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26220 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
26230 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
26240 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
26250 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
26260 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
26270 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
26280 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 35 33 5d 0a  ts:.** [H16253].
26290 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
262a0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
262b0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
262c0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
262d0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
262e0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
262f0 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32  a {H16270} <S202
26300 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  00>.**.** The fo
26310 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
26320 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
26330 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
26340 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
26350 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
26360 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
26370 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
26380 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
26390 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
263a0 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
263b0 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
263c0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
263d0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
263e0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
263f0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
26400 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
26410 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
26420 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
26430 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
26440 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
26450 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
26460 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
26470 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
26480 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
26490 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
264a0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
264b0 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
264c0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
264d0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
264e0 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
264f0 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
26500 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
26510 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
26520 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
26530 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
26540 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
26550 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
26560 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
26570 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
26580 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
26590 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
265a0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
265b0 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
265c0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
265d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
265e0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
265f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26600 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
26610 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
26620 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
26630 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
26640 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
26650 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
26660 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
26670 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
26680 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26690 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61  . If no metadata
266a0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
266b0 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
266c0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
266d0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
266e0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
266f0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
26700 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
26710 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
26720 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
26730 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
26740 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
26750 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
26760 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
26770 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26780 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
26790 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
267a0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
267b0 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
267c0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
267d0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
267e0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
267f0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
26800 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26810 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
26820 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
26830 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
26840 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
26850 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
26860 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
26870 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
26880 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e  d..** If it is n
26890 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
268a0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
268b0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
268c0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
268d0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
268e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
268f0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
26900 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
26910 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
26920 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
26930 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
26940 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
26950 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
26960 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
26970 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
26980 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
26990 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
269a0 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
269b0 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
269c0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
269d0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
269e0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54   at any time.  T
269f0 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
26a00 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
26a10 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
26a20 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
26a30 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
26a40 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
26a50 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
26a60 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
26a70 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
26a80 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
26a90 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
26aa0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
26ab0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
26ac0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
26ad0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
26ae0 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c   and SQL variabl
26af0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
26b00 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
26b10 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
26b20 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
26b30 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
26b40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
26b50 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ning..**.** Requ
26b60 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
26b70 36 32 37 32 5d 20 5b 48 31 36 32 37 34 5d 20 5b  6272] [H16274] [
26b80 48 31 36 32 37 36 5d 20 5b 48 31 36 32 37 37 5d  H16276] [H16277]
26b90 20 5b 48 31 36 32 37 38 5d 20 5b 48 31 36 32 37   [H16278] [H1627
26ba0 39 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  9].*/.void *sqli
26bb0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
26bc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
26bd0 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
26be0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
26bf0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
26c00 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
26c10 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
26c20 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
26c30 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
26c40 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
26c50 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
26c60 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c  avior {H10280} <
26c70 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30100>.**.** Th
26c80 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
26c90 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
26ca0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
26cb0 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
26cc0 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
26cd0 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
26ce0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
26cf0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
26d00 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
26d10 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
26d20 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
26d30 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
26d40 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
26d50 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
26d60 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
26d70 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
26d80 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
26d90 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a  destroyed.  The.
26da0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
26db0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
26dc0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
26dd0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
26de0 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
26df0 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
26e00 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
26e10 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
26e20 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
26e30 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
26e40 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
26e50 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
26e60 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
26e70 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
26e80 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
26e90 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
26ea0 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
26eb0 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
26ec0 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
26ed0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
26ee0 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
26ef0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
26f00 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
26f10 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
26f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26f30 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
26f40 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
26f50 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
26f60 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
26f70 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
26f80 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
26f90 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30   {H16400} <S2020
26fa0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
26fb0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
26fc0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
26fd0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
26fe0 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
26ff0 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
27000 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
27010 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
27020 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
27030 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
27040 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
27050 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
27060 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
27070 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
27080 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
27090 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
270a0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
270b0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
270c0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
270d0 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
270e0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
270f0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
27100 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
27110 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
27120 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
27130 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
27140 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
27150 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
27160 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27170 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
27180 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
27190 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
271a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
271b0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
271c0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
271d0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
271e0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
271f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
27200 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
27210 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
27220 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
27230 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
27240 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27250 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
27260 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
27270 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
27280 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
27290 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
272a0 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
272b0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
272c0 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
272d0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
272e0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
272f0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
27300 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
27310 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
27320 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
27330 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
27340 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
27350 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
27360 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27370 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
27380 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
27390 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
273a0 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
273b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
273c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
273d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
273e0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
273f0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
27400 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
27410 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
27420 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
27430 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ion..** SQLite u
27440 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
27450 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
27460 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
27470 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
27480 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
27490 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
274a0 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
274b0 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
274c0 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c  or message.  SQL
274d0 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
274e0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
274f0 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
27500 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27510 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
27520 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72   SQLite.** inter
27530 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
27540 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
27550 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
27560 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
27570 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
27580 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20  .  If the third 
27590 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
275a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
275b0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
275c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
275d0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
275e0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
275f0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
27600 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
27610 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
27620 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
27630 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65  acter..** If the
27640 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
27650 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
27660 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
27670 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27680 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
27690 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
276a0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
276b0 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
276c0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
276d0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
276e0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
276f0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
27700 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
27710 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
27720 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
27730 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
27740 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
27750 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
27760 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
27770 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
27780 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
27790 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
277a0 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
277b0 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
277c0 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
277d0 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
277e0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68  hout harm..** Th
277f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
27800 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
27810 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
27820 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
27830 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
27840 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
27850 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
27860 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64   function.  By d
27870 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
27880 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
27890 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75  ITE_ERROR.  A su
278a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
278b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
278c0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
278d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
278e0 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
278f0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
27900 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
27910 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27920 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
27930 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
27940 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
27950 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
27960 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
27970 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
27980 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72   to long to repr
27990 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  esent..**.** The
279a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
279b0 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
279c0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
279d0 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
279e0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
279f0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
27a00 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
27a10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27a20 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
27a30 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
27a40 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
27a50 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
27a60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
27a70 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
27a80 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
27a90 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
27aa0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
27ab0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
27ac0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
27ad0 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
27ae0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
27af0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
27b00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
27b10 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
27b20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
27b30 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
27b40 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
27b50 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
27b60 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
27b70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
27b80 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  l() interface se
27b90 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
27ba0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
27bb0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27bc0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
27bd0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
27be0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27bf0 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
27c00 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
27c10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
27c20 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
27c30 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
27c40 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
27c50 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
27c60 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
27c70 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
27c80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
27c90 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
27ca0 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
27cb0 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
27cc0 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
27cd0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
27ce0 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
27cf0 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
27d00 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
27d10 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
27d20 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73  .** SQLite takes
27d30 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
27d40 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
27d50 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
27d60 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
27d70 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
27d80 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
27d90 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68  rfaces..** If th
27da0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
27db0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
27dc0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
27dd0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
27de0 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
27df0 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
27e00 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
27e10 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
27e20 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
27e30 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
27e40 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
27e50 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
27e60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
27e70 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
27e80 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
27e90 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
27ea0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
27eb0 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
27ec0 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
27ed0 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
27ee0 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
27ef0 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
27f00 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
27f10 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a  unction result..
27f20 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
27f30 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
27f40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
27f50 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
27f60 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
27f70 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
27f80 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
27f90 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
27fa0 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
27fb0 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
27fc0 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
27fd0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
27fe0 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
27ff0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
28000 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  at result..** If
28010 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
28020 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
28030 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
28040 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
28050 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
28060 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
28070 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
28080 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
28090 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
280a0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
280b0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
280c0 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
280d0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
280e0 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
280f0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
28100 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
28110 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
28120 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
28130 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
28140 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
28150 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
28160 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
28170 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
28180 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
28190 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
281a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
281b0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
281c0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
281d0 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
281e0 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
281f0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
28200 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
28210 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
28220 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
28230 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
28240 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
28250 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
28260 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
28270 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
28280 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
28290 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
282a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
282b0 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
282c0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
282d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
282e0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
282f0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
28300 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ter.  The.** sql
28310 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
28320 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
28330 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
28340 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
28350 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
28360 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
28370 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
28380 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
28390 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
283a0 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
283b0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
283c0 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
283d0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
283e0 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73  * A [protected s
283f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28400 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
28410 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
28420 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
28430 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
28440 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
28450 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
28460 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
28470 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
28480 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
28490 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
284a0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
284b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
284c0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
284d0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
284e0 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
284f0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
28500 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
28510 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
28520 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
28530 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
28540 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
28550 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
28560 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
28570 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
28580 2a 2a 20 5b 48 31 36 34 30 33 5d 20 5b 48 31 36  ** [H16403] [H16
28590 34 30 36 5d 20 5b 48 31 36 34 30 39 5d 20 5b 48  406] [H16409] [H
285a0 31 36 34 31 32 5d 20 5b 48 31 36 34 31 35 5d 20  16412] [H16415] 
285b0 5b 48 31 36 34 31 38 5d 20 5b 48 31 36 34 32 31  [H16418] [H16421
285c0 5d 20 5b 48 31 36 34 32 34 5d 0a 2a 2a 20 5b 48  ] [H16424].** [H
285d0 31 36 34 32 37 5d 20 5b 48 31 36 34 33 30 5d 20  16427] [H16430] 
285e0 5b 48 31 36 34 33 33 5d 20 5b 48 31 36 34 33 36  [H16433] [H16436
285f0 5d 20 5b 48 31 36 34 33 39 5d 20 5b 48 31 36 34  ] [H16439] [H164
28600 34 32 5d 20 5b 48 31 36 34 34 35 5d 20 5b 48 31  42] [H16445] [H1
28610 36 34 34 38 5d 0a 2a 2a 20 5b 48 31 36 34 35 31  6448].** [H16451
28620 5d 20 5b 48 31 36 34 35 34 5d 20 5b 48 31 36 34  ] [H16454] [H164
28630 35 37 5d 20 5b 48 31 36 34 36 30 5d 20 5b 48 31  57] [H16460] [H1
28640 36 34 36 33 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71  6463].*/.void sq
28650 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
28660 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
28670 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
28680 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
28690 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
286a0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
286b0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
286c0 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
286d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
286e0 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
286f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
28700 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
28710 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28720 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
28730 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
28740 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
28750 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28760 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
28770 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
28780 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
28790 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
287a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
287b0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
287c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
287d0 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
287e0 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
287f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
28800 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
28810 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
28820 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
28830 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
28840 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
28850 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
28860 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
28870 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28880 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
28890 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
288a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
288b0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
288c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
288d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
288e0 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
288f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
28900 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
28910 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
28920 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
28930 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
28940 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
28950 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
28960 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
28970 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
28980 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
28990 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
289a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
289b0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
289c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
289d0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
289e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
289f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28a00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
28a10 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
28a20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
28a30 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
28a40 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
28a50 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
28a60 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20  uences {H16600} 
28a70 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20300>.**.** T
28a80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
28a90 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e  re used to add n
28aa0 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
28ab0 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a  uences to the.**
28ac0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
28ad0 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
28ae0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
28af0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
28b00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
28b10 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
28b20 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
28b30 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
28b40 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
28b50 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
28b60 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
28b70 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
28b80 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
28b90 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
28ba0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
28bb0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
28bc0 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a   In all cases.**
28bd0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73   the name is pas
28be0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
28bf0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
28c00 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ent..**.** The t
28c10 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61  hird argument ma
28c20 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  y be one of the 
28c30 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
28c40 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_UTF8],.** [SQL
28c50 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72  ITE_UTF16LE], or
28c60 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
28c70 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
28c80 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70  at the user-supp
28c90 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  lied.** routine 
28ca0 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61  expects to be pa
28cb0 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f  ssed pointers to
28cc0 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64   strings encoded
28cd0 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a   using UTF-8,.**
28ce0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65   UTF-16 little-e
28cf0 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
28d00 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73   big-endian, res
28d10 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a  pectively. The.*
28d20 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
28d30 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
28d40 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 6f  SQLITE_UTF16] to
28d50 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 74   indicate that t
28d60 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78  he routine.** ex
28d70 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
28d80 6f 20 62 65 20 55 54 46 2d 31 36 20 73 74 72 69  o be UTF-16 stri
28d90 6e 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69 76  ngs in the nativ
28da0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f 72  e byte order, or
28db0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
28dc0 20 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f   can be [SQLITE_
28dd0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69  UTF16_ALIGNED] i
28de0 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75  f the.** the rou
28df0 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69  tine expects poi
28e00 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20  nters to 16-bit 
28e10 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72  word aligned str
28e20 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31  ings.** of UTF-1
28e30 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
28e40 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
28e50 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
28e60 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
28e70 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
28e80 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
28e90 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
28ea0 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  .  If it is NULL
28eb0 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
28ec0 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
28ed0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
28ee0 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
28ef0 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
28f00 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
28f10 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74  ..** Each time t
28f20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
28f30 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
28f40 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
28f50 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20  is passed.** as 
28f60 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
28f70 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ter a copy of th
28f80 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61  e void* passed a
28f90 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
28fa0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
28fb0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
28fc0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
28fd0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
28fe0 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
28ff0 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
29000 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
29010 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
29020 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
29030 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
29040 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
29050 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
29060 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
29070 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
29080 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
29090 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
290a0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
290b0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
290c0 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
290d0 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
290e0 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  }  The applicati
290f0 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
29100 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
29110 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
29120 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
29130 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20  positive if the 
29140 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
29150 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71  less than,.** eq
29160 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
29170 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
29180 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  nd string. i.e. 
29190 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
291a0 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
291b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
291c0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
291d0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
291e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
291f0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
29200 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
29210 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
29220 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
29230 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
29240 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
29250 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
29260 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
29270 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
29280 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
29290 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
292a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
292b0 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
292c0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
292d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
292e0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c  ion_v2()..** Col
292f0 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74  lations are dest
29300 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20  royed when they 
29310 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
29320 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
29330 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f   the.** collatio
29340 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
29350 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
29360 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29370 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
29380 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
29390 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
293a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
293b0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
293c0 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
293d0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
293e0 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
293f0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
29400 73 3a 0a 2a 2a 20 5b 48 31 36 36 30 33 5d 20 5b  s:.** [H16603] [
29410 48 31 36 36 30 34 5d 20 5b 48 31 36 36 30 36 5d  H16604] [H16606]
29420 20 5b 48 31 36 36 30 39 5d 20 5b 48 31 36 36 31   [H16609] [H1661
29430 32 5d 20 5b 48 31 36 36 31 35 5d 20 5b 48 31 36  2] [H16615] [H16
29440 36 31 38 5d 20 5b 48 31 36 36 32 31 5d 0a 2a 2a  618] [H16621].**
29450 20 5b 48 31 36 36 32 34 5d 20 5b 48 31 36 36 32   [H16624] [H1662
29460 37 5d 20 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a 69  7] [H16630].*/.i
29470 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
29480 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
29490 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
294a0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
294b0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
294c0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
294d0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
294e0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
294f0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
29500 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
29510 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29520 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
29530 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
29540 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
29550 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
29560 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
29570 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
29580 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
29590 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
295a0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
295b0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
295c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
295d0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
295e0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
295f0 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
29600 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
29610 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
29620 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
29630 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
29640 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
29650 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29660 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
29670 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37   Callbacks {H167
29680 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a  00} <S20300>.**.
29690 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69  ** To avoid havi
296a0 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
296b0 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
296c0 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
296d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
296e0 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
296f0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
29700 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
29710 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
29720 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
29730 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61  ection] to be ca
29740 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  lled whenever an
29750 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
29760 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
29770 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
29780 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74  .** If the funct
29790 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
297a0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
297b0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
297c0 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
297d0 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
297e0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
297f0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
29800 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
29810 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
29820 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36  d in UTF-8. {H16
29830 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f  703} If sqlite3_
29840 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
29850 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
29860 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
29870 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
29880 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
29890 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
298a0 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65   A call to eithe
298b0 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
298c0 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67  ces any existing
298d0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
298e0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
298f0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
29900 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29910 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
29920 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
29930 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
29940 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
29950 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
29960 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
29970 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
29980 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
29990 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
299a0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
299b0 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
299c0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
299d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
299e0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
299f0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
29a00 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
29a10 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
29a20 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
29a30 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
29a40 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
29a50 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
29a60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29a70 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
29a80 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
29a90 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
29aa0 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ence..**.** The 
29ab0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
29ac0 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
29ad0 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
29ae0 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
29af0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29b00 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
29b10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
29b20 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
29b30 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
29b40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
29b50 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  2()]..**.** Requ
29b60 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
29b70 36 37 30 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b  6702] [H16704] [
29b80 48 31 36 37 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73  H16706].*/.int s
29b90 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
29ba0 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
29bb0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
29bc0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
29bd0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
29be0 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
29bf0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
29c00 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
29c10 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
29c20 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
29c30 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
29c40 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
29c50 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
29c60 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
29c70 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
29c80 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
29c90 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
29ca0 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
29cb0 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
29cc0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
29cd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
29ce0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
29cf0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
29d00 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
29d10 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
29d20 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
29d30 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
29d40 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
29d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29d60 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
29d70 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
29d80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
29d90 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
29da0 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
29db0 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
29dc0 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
29dd0 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
29de0 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
29df0 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
29e00 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
29e10 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
29e20 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
29e30 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
29e40 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
29e50 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
29e60 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
29e70 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
29e80 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
29e90 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
29ea0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
29eb0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
29ec0 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
29ed0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
29ee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
29ef0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
29f00 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
29f10 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
29f20 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
29f30 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
29f40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29f50 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
29f60 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
29f70 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53  Time {H10530} <S
29f80 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  40410>.**.** The
29f90 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
29fa0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
29fb0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
29fc0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
29fd0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
29fe0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
29ff0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2a000 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
2a010 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
2a020 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
2a030 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
2a040 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
2a050 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
2a060 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
2a070 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
2a080 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
2a090 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
2a0a0 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72  p to.** the near
2a0b0 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20  est second. The 
2a0c0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
2a0d0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
2a0e0 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75  actually.** requ
2a0f0 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
2a100 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
2a110 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2a120 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
2a130 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
2a140 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
2a150 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
2a160 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
2a170 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
2a180 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  s] object..**.**
2a190 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
2a1a0 48 31 30 35 33 33 5d 20 5b 48 31 30 35 33 36 5d  H10533] [H10536]
2a1b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a1c0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
2a1d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2a1e0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
2a1f0 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
2a200 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d  y Files {H10310}
2a210 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
2a220 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
2a230 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
2a240 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
2a250 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
2a260 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
2a270 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
2a280 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
2a290 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
2a2a0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
2a2b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
2a2c0 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
2a2d0 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68  irectory.  If th
2a2e0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2a2f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2a300 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
2a310 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
2a320 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
2a330 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
2a340 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
2a350 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
2a360 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2a370 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2a380 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
2a390 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
2a3a0 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
2a3b0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2a3c0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2a3d0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
2a3e0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2a3f0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
2a400 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
2a410 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
2a420 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
2a430 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
2a440 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
2a450 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
2a460 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
2a470 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
2a480 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
2a490 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
2a4a0 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
2a4b0 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
2a4c0 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
2a4d0 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
2a4e0 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
2a4f0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
2a500 20 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   The [temp_store
2a510 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2a520 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
2a530 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
2a540 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
2a550 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
2a560 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2a570 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
2a580 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
2a590 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2a5a0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2a5b0 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
2a5c0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
2a5d0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
2a5e0 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
2a5f0 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
2a600 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2a610 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
2a620 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
2a630 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
2a640 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
2a650 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
2a660 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
2a670 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
2a680 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
2a690 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
2a6a0 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
2a6b0 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
2a6c0 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
2a6d0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
2a6e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2a6f0 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
2a700 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
2a710 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2a720 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2a730 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
2a740 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
2a750 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
2a760 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
2a770 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
2a780 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
2a790 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b  to-Commit Mode {
2a7a0 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e  H12930} <S60200>
2a7b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2a7c0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
2a7d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2a7e0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
2a7f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2a800 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
2a810 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
2a820 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
2a830 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
2a840 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
2a850 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
2a860 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74  spectively.  Aut
2a870 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2a880 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
2a890 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  * Autocommit mod
2a8a0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2a8b0 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
2a8c0 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d  ment..** Autocom
2a8d0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65  mit mode is re-e
2a8e0 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d  nabled by a [COM
2a8f0 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
2a900 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  K]..**.** If cer
2a910 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
2a920 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
2a930 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
2a940 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
2a950 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
2a960 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  n (errors includ
2a970 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
2a980 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
2a990 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  ],.** [SQLITE_NO
2a9a0 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
2a9b0 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
2a9c0 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
2a9d0 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
2a9e0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
2a9f0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
2aa00 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
2aa10 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
2aa20 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51  d out whether SQ
2aa30 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
2aa40 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
2aa50 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
2aa60 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
2aa70 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
2aa80 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2aa90 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
2aaa0 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
2aab0 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
2aac0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
2aad0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  ** connection wh
2aae0 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
2aaf0 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
2ab00 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
2ab10 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ue.** is undefin
2ab20 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ed..**.** Requir
2ab30 65 6d 65 6e 74 73 3a 20 5b 48 31 32 39 33 31 5d  ements: [H12931]
2ab40 20 5b 48 31 32 39 33 32 5d 20 5b 48 31 32 39 33   [H12932] [H1293
2ab50 33 5d 20 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a 69  3] [H12934].*/.i
2ab60 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
2ab70 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
2ab80 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
2ab90 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44  3REF: Find The D
2aba0 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
2abb0 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
2abc0 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20  tement {H13120} 
2abd0 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60600>.**.** T
2abe0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
2abf0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
2ac00 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
2ac10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2ac20 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
2ac30 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
2ac40 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
2ac50 67 73 2e 20 20 54 68 65 20 5b 64 61 74 61 62 61  gs.  The [databa
2ac60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
2ac70 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2ac80 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
2ac90 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  is the same [dat
2aca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2acb0 5d 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  ] that was the f
2acc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
2acd0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2ace0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
2acf0 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
2ad00 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
2ad10 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
2ad20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2ad30 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
2ad40 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  e..**.** Require
2ad50 6d 65 6e 74 73 3a 20 5b 48 31 33 31 32 33 5d 0a  ments: [H13123].
2ad60 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2ad70 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
2ad80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2ad90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2ada0 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
2adb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2adc0 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30  {H13140} <S60600
2add0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
2ade0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2adf0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2ae00 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
2ae10 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a  tatement] after.
2ae20 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61  ** pStmt associa
2ae30 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
2ae40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ae50 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d  n] pDb.  If pStm
2ae60 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
2ae70 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
2ae80 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2ae90 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
2aea0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2aeb0 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
2aec0 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
2aed0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
2aee0 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72  b.  If no prepar
2aef0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2af00 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f  satisfies the co
2af10 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73  nditions of this
2af20 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74   routine, it ret
2af30 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  urns NULL..**.**
2af40 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
2af50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74  onnection] point
2af60 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74  er D in a call t
2af70 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65  o.** [sqlite3_ne
2af80 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75  xt_stmt(D,S)] mu
2af90 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f  st refer to an o
2afa0 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  pen database.** 
2afb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69  connection and i
2afc0 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73  n particular mus
2afd0 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20  t not be a NULL 
2afe0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52  pointer..**.** R
2aff0 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
2b000 33 31 34 33 5d 20 5b 48 31 33 31 34 36 5d 20 5b  3143] [H13146] [
2b010 48 31 33 31 34 39 5d 20 5b 48 31 33 31 35 32 5d  H13149] [H13152]
2b020 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
2b030 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
2b040 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
2b050 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
2b060 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2b070 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
2b080 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
2b090 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2b0a0 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36  cks {H12950} <S6
2b0b0 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0400>.**.** The 
2b0c0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2b0d0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2b0e0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2b0f0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2b100 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2b110 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2b120 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54  ction is [COMMIT
2b130 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a   | committed]..*
2b140 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
2b150 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2b160 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2b170 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
2b180 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2b190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b1a0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2b1b0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
2b1c0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2b1d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2b1e0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
2b1f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
2b200 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2b210 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
2b220 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20   is [ROLLBACK | 
2b230 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a  rolled back]..**
2b240 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
2b250 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
2b260 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2b270 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
2b280 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
2b290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b2a0 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
2b2b0 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67  .** The pArg arg
2b2c0 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
2b2d0 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
2b2e0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74  allback..** If t
2b2f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
2b300 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
2b310 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
2b320 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
2b330 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
2b340 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
2b350 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ollback..**.** I
2b360 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
2b370 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
2b380 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
2b390 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20  s.** pArg value 
2b3a0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
2b3b0 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
2b3c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2b3d0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
2b3e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2b3f0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
2b400 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
2b410 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
2b420 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
2b430 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
2b440 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
2b450 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
2b460 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
2b470 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
2b480 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
2b490 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
2b4a0 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
2b4b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2b4c0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
2b4d0 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
2b4e0 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
2b4f0 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
2b500 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
2b510 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
2b520 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2b530 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2b540 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
2b550 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
2b560 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
2b570 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
2b580 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
2b590 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
2b5a0 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55  Registering a NU
2b5b0 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  LL function disa
2b5c0 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  bles the callbac
2b5d0 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  k..**.** When th
2b5e0 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
2b5f0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
2b600 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
2b610 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65   [COMMIT].** ope
2b620 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65  ration is allowe
2b630 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f  d to continue no
2b640 72 6d 61 6c 6c 79 2e 20 20 49 66 20 74 68 65 20  rmally.  If the 
2b650 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
2b660 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
2b670 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
2b680 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
2b690 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
2b6a0 5d 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  ]..** The rollba
2b6b0 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b  ck hook is invok
2b6c0 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b  ed on a rollback
2b6d0 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72   that results fr
2b6e0 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68  om a commit.** h
2b6f0 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f  ook returning no
2b700 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20  n-zero, just as 
2b710 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68  it would be with
2b720 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62   any other rollb
2b730 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74  ack..**.** For t
2b740 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
2b750 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73  his API, a trans
2b760 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74  action is said t
2b770 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72  o have been.** r
2b780 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
2b790 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
2b7a0 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
2b7b0 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
2b7c0 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
2b7d0 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
2b7e0 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
2b7f0 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
2b800 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
2b810 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
2b820 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
2b830 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
2b840 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
2b850 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
2b860 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2b870 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
2b880 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  d..** The rollba
2b890 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
2b8a0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
2b8b0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
2b8c0 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  * rolled back be
2b8d0 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63  cause a commit c
2b8e0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64  allback returned
2b8f0 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74   non-zero..** <t
2b900 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68  odo> Check on th
2b910 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  is </todo>.**.**
2b920 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2b930 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2b940 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
2b950 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
2b960 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31 5d  nts:.** [H12951]
2b970 20 5b 48 31 32 39 35 32 5d 20 5b 48 31 32 39 35   [H12952] [H1295
2b980 33 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48 31 32  3] [H12954] [H12
2b990 39 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31 5d  955].** [H12961]
2b9a0 20 5b 48 31 32 39 36 32 5d 20 5b 48 31 32 39 36   [H12962] [H1296
2b9b0 33 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a 76  3] [H12964].*/.v
2b9c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
2b9d0 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
2b9e0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
2b9f0 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
2ba00 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
2ba10 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
2ba20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
2ba30 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
2ba40 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
2ba50 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
2ba60 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  on Callbacks {H1
2ba70 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2970} <S60400>.*
2ba80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2ba90 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
2baa0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2bab0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
2bac0 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
2bad0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2bae0 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
2baf0 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
2bb00 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2bb10 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2bb20 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
2bb30 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2bb40 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e  r deleted..** An
2bb50 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2bb60 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2bb70 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
2bb80 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
2bb90 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2bba0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2bbb0 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dden..**.** The 
2bbc0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2bbd0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
2bbe0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
2bbf0 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a  invoke when a.**
2bc00 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2bc10 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2bc20 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eted..** The fir
2bc30 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2bc40 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
2bc50 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
2bc60 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
2bc70 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
2bc80 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20  _hook()..** The 
2bc90 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
2bca0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
2bcb0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
2bcc0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
2bcd0 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  TE],.** or [SQLI
2bce0 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65  TE_UPDATE], depe
2bcf0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
2bd00 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
2bd10 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  ed the callback.
2bd20 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2bd30 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  ..** The third a
2bd40 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
2bd50 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
2bd60 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
2bd70 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
2bd80 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
2bd90 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
2bda0 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
2bdb0 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c  ow..** The final
2bdc0 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
2bdd0 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69  ter is the [rowi
2bde0 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a  d] of the row..*
2bdf0 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66  * In the case of
2be00 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
2be10 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
2be20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
2be30 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
2be40 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
2be50 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
2be60 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
2be70 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
2be80 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
2be90 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
2bea0 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
2beb0 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49  quence)..**.** I
2bec0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
2bed0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
2bee0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
2bef0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2bf00 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e  when duplication
2bf10 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
2bf20 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a  d because of an.
2bf30 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  ** [ON CONFLICT 
2bf40 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45  | ON CONFLICT RE
2bf50 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20  PLACE] clause.  
2bf60 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74  Nor is the updat
2bf70 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65  e hook.** invoke
2bf80 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20  d when rows are 
2bf90 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68  deleted using th
2bfa0 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  e [truncate opti
2bfb0 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  mization]..** Th
2bfc0 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66  e exceptions def
2bfd0 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72  ined in this par
2bfe0 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61  agraph might cha
2bff0 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
2c000 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
2c010 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
2c020 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c  update hook impl
2c030 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
2c040 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
2c050 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
2c060 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2c070 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2c080 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64   invoked the upd
2c090 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61  ate hook.  Any a
2c0a0 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
2c0b0 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2c0c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2c0d0 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
2c0e0 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
2c0f0 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
2c100 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2c110 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
2c120 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74  ggered the updat
2c130 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  e hook..** Note 
2c140 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
2c150 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2c160 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c170 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
2c180 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
2c190 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
2c1a0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
2c1b0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
2c1c0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
2c1d0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74  If another funct
2c1e0 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73  ion was previous
2c1f0 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69  ly registered, i
2c200 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a  ts pArg value.**
2c210 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
2c220 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73  therwise NULL is
2c230 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2c240 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2c250 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2c260 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
2c270 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2c280 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
2c290 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
2c2a0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37  ments:.** [H1297
2c2b0 31 5d 20 5b 48 31 32 39 37 33 5d 20 5b 48 31 32  1] [H12973] [H12
2c2c0 39 37 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48  975] [H12977] [H
2c2d0 31 32 39 37 39 5d 20 5b 48 31 32 39 38 31 5d 20  12979] [H12981] 
2c2e0 5b 48 31 32 39 38 33 5d 20 5b 48 31 32 39 38 36  [H12983] [H12986
2c2f0 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ].*/.void *sqlit
2c300 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
2c310 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2c320 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
2c330 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
2c340 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
2c350 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
2c360 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
2c370 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
2c380 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
2c390 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b 48  d Pager Cache {H
2c3a0 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a  10330} <S30900>.
2c3b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
2c3c0 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a  ared cache}.**.*
2c3d0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  * This routine e
2c3e0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
2c3f0 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
2c400 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
2c410 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
2c420 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
2c430 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
2c440 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c450 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
2c460 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
2c470 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
2c480 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
2c490 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
2c4a0 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
2c4b0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
2c4c0 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a  nt is false..**.
2c4d0 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67  ** Cache sharing
2c4e0 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
2c4f0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
2c500 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
2c510 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
2c520 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
2c530 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
2c540 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
2c550 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
2c560 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
2c570 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
2c580 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
2c590 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2c5a0 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72  * The cache shar
2c5b0 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
2c5c0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
2c5d0 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
2c5e0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
2c5f0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2c600 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2c610 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
2c620 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2c630 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
2c640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c650 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
2c660 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a  he sharing mode.
2c670 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65  ** that was in e
2c680 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
2c690 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
2c6a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ed..**.** Virtua
2c6b0 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20  l tables cannot 
2c6c0 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73  be used with a s
2c6d0 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68  hared cache.  Wh
2c6e0 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  en shared.** cac
2c6f0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74  he is enabled, t
2c700 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2c710 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49  te_module()] API
2c720 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
2c730 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  r.** virtual tab
2c740 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  les will always 
2c750 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
2c760 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2c770 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
2c780 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
2c790 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
2c7a0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
2c7b0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2c7c0 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
2c7d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  ] is returned ot
2c7e0 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53  herwise..**.** S
2c7f0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
2c800 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
2c810 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
2c820 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
2c830 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2c840 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
2c850 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
2c860 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
2c870 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
2c880 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
2c890 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
2c8a0 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
2c8b0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
2c8c0 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71   Mode].**.** Req
2c8d0 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33  uirements: [H103
2c8e0 33 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48 31  31] [H10336] [H1
2c8f0 30 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a  0337] [H10339].*
2c900 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2c910 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
2c920 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
2c930 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74  API3REF: Attempt
2c940 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
2c950 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53  mory {H17340} <S
2c960 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30220>.**.** The
2c970 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2c980 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66  _memory() interf
2c990 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
2c9a0 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20  free N bytes.** 
2c9b0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
2c9c0 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
2c9d0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
2c9e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a  ory allocations.
2c9f0 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ** held by the d
2ca00 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
2ca10 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75   {END}  Memory u
2ca20 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2ca30 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2ca40 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2ca50 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2ca60 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2ca70 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2ca80 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2ca90 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
2caa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2cab0 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
2cac0 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
2cad0 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
2cae0 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
2caf0 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
2cb00 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2cb10 73 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31 37  s: [H17341] [H17
2cb20 33 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  342].*/.int sqli
2cb30 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2cb40 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
2cb50 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
2cb60 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
2cb70 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c   Size {H17350} <
2cb80 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30220>.**.** Th
2cb90 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
2cba0 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65  eap_limit() inte
2cbb0 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22  rface places a "
2cbc0 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f  soft" limit.** o
2cbd0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
2cbe0 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
2cbf0 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
2cc00 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  d by SQLite..** 
2cc10 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
2cc20 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
2cc30 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c  uested that woul
2cc40 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
2cc50 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
2cc60 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2cc70 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69  e_memory()] is i
2cc80 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a  nvoked one or.**
2cc90 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
2cca0 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
2ccb0 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
2ccc0 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f  ocation is perfo
2ccd0 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rmed..**.** The 
2cce0 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20  limit is called 
2ccf0 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20  "soft", because 
2cd00 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  if [sqlite3_rele
2cd10 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a  ase_memory()].**
2cd20 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66   cannot free suf
2cd30 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
2cd40 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
2cd50 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
2cd60 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
2cd70 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
2cd80 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
2cd90 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
2cda0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
2cdb0 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  *.** A negative 
2cdc0 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
2cdd0 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74  r N means that t
2cde0 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20  here is no soft 
2cdf0 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a  heap limit and.*
2ce00 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
2ce10 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
2ce20 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  l only be called
2ce30 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
2ce40 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68  exhausted..** Th
2ce50 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
2ce60 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2ce70 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
2ce80 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
2ce90 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72  kes a best effor
2cea0 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73  t to honor the s
2ceb0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a  oft heap limit..
2cec0 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f  ** But if the so
2ced0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
2cee0 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c  nnot be honored,
2cef0 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
2cf00 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
2cf10 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
2cf20 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  ification.  This
2cf30 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
2cf40 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61  t is.** called a
2cf50 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20   "soft" limit.  
2cf60 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  It is advisory o
2cf70 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  nly..**.** Prior
2cf80 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
2cf90 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72  on 3.5.0, this r
2cfa0 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73  outine only cons
2cfb0 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f  trained the memo
2cfc0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ry.** allocated 
2cfd0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
2cfe0 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68  ad - the same th
2cff0 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
2d000 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75  is routine.** ru
2d010 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ns.  Beginning w
2d020 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
2d030 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f  on 3.5.0, the so
2d040 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
2d050 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61  .** applied to a
2d060 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20  ll threads. The 
2d070 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20  value specified 
2d080 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2d090 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e  p limit.** is an
2d0a0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
2d0b0 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79  the total memory
2d0c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
2d0d0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a  all threads. In.
2d0e0 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  ** version 3.5.0
2d0f0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63   there is no mec
2d100 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74  hanism for limit
2d110 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61  ing the heap usa
2d120 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69  ge for.** indivi
2d130 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a  dual threads..**
2d140 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2d150 3a 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48  :.** [H16351] [H
2d160 31 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20  16352] [H16353] 
2d170 5b 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35  [H16354] [H16355
2d180 5d 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f  ] [H16358].*/.vo
2d190 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  id sqlite3_soft_
2d1a0 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b  heap_limit(int);
2d1b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d1c0 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
2d1d0 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
2d1e0 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48 31  n Of A Table {H1
2d1f0 32 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a  2850} <S60300>.*
2d200 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2d210 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
2d220 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
2d230 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
2d240 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
2d250 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
2d260 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
2d270 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d280 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2d290 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
2d2a0 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
2d2b0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
2d2c0 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
2d2d0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
2d2e0 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
2d2f0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
2d300 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
2d310 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64  tion. The second
2d320 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69   parameter is ei
2d330 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66  ther the name of
2d340 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2d350 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22   (i.e. "main", "
2d360 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61  temp" or an atta
2d370 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
2d380 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
2d390 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
2d3a0 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20   or NULL. If it 
2d3b0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
2d3c0 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
2d3d0 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
2d3e0 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
2d3f0 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
2d400 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64  e algorithm used
2d410 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
2d420 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65   engine to.** re
2d430 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
2d440 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
2d450 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  es..**.** The th
2d460 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
2d470 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2d480 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
2d490 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
2d4a0 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
2d4b0 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
2d4c0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2d4d0 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
2d4e0 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
2d4f0 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
2d500 2a 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20 72  ** Metadata is r
2d510 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
2d520 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
2d530 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
2d540 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20  d as the 5th.** 
2d550 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
2d560 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2d570 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20  s function. Any 
2d580 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e  of these argumen
2d590 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c  ts may be.** NUL
2d5a0 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
2d5b0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2d5c0 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
2d5d0 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65  tadata is omitte
2d5e0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d..**.** <blockq
2d5f0 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2d600 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2d610 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65  tr><th> Paramete
2d620 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72  r <th> Output<br
2d630 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63  >Type <th>  Desc
2d640 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  ription.**.** <t
2d650 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20  r><td> 5th <td> 
2d660 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
2d670 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74   Data type.** <t
2d680 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20  r><td> 6th <td> 
2d690 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
2d6a0 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74   Name of default
2d6b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2d6c0 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nce.** <tr><td> 
2d6d0 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  7th <td> int    
2d6e0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
2d6f0 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  f column has a N
2d700 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
2d710 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38  nt.** <tr><td> 8
2d720 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2d730 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2d740 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
2d750 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
2d760 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39  EY.** <tr><td> 9
2d770 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2d780 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2d790 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f   column is [AUTO
2d7a0 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f  INCREMENT].** </
2d7b0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2d7c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
2d7d0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
2d7e0 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
2d7f0 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
2d800 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
2d810 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
2d820 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
2d830 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
2d840 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
2d850 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
2d860 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
2d870 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2d880 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
2d890 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2d8a0 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
2d8b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2d8c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
2d8d0 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
2d8e0 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64  column is "rowid
2d8f0 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f  ", "oid" or "_ro
2d900 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20  wid_" and an.** 
2d910 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2d920 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73   KEY] column has
2d930 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79   been explicitly
2d940 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20   declared, then 
2d950 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61  the output.** pa
2d960 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
2d970 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69   for the explici
2d980 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
2d990 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73  umn. If there is
2d9a0 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
2d9b0 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
2d9c0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
2d9d0 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
2d9e0 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
2d9f0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
2da00 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
2da10 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
2da20 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
2da30 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
2da40 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
2da50 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
2da60 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
2da70 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
2da80 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
2da90 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
2daa0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  e>.**.** This fu
2dab0 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20  nction may load 
2dac0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65  one or more sche
2dad0 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73  mas from databas
2dae0 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a  e files. If an.*
2daf0 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  * error occurs d
2db00 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65  uring this proce
2db10 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  ss, or if the re
2db20 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72  quested table or
2db30 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f   column.** canno
2db40 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b  t be found, an [
2db50 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2db60 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
2db70 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66  rror message lef
2db80 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74  t.** in the [dat
2db90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2dba0 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  ] (to be retriev
2dbb0 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
2dbc0 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a  _errmsg())..**.*
2dbd0 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e  * This API is on
2dbe0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2dbf0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2dc00 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2dc10 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2dc20 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2dc30 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2dc40 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
2dc50 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2dc60 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
2dc70 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
2dc80 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2dc90 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
2dca0 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
2dcb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
2dcc0 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
2dcd0 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
2dce0 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
2dcf0 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
2dd00 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
2dd10 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
2dd20 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
2dd30 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
2dd40 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
2dd50 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
2dd60 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
2dd70 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
2dd80 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
2dd90 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
2dda0 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
2ddb0 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
2ddc0 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
2ddd0 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
2dde0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
2ddf0 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
2de00 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2de10 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
2de20 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
2de30 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2de40 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2de50 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
2de60 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
2de70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2de80 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2de90 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
2dea0 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
2deb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2dec0 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
2ded0 69 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32  ion {H12600} <S2
2dee0 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0500>.**.** This
2def0 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73   interface loads
2df00 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
2df10 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f  sion library fro
2df20 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65  m the named file
2df30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d  ..**.** {H12601}
2df40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
2df50 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2df60 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2df70 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20   to load an.**  
2df80 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65          SQLite e
2df90 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
2dfa0 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
2dfb0 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a  e file zFile..**
2dfc0 0a 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65  .** {H12602} The
2dfd0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
2dfe0 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  zProc..**.** {H1
2dff0 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20  2603} zProc may 
2e000 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63  be 0, in which c
2e010 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ase the name of 
2e020 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  the entry point.
2e030 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
2e040 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33  ults to "sqlite3
2e050 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22  _extension_init"
2e060 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d  ..**.** {H12604}
2e070 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61   The sqlite3_loa
2e080 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2e090 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65  terface shall re
2e0a0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
2e0b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
2e0c0 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
2e0d0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
2e0e0 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
2e0f0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30  ng..**.** {H1260
2e100 35 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  5} If an error o
2e110 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
2e120 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
2e130 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
2e140 20 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f    [sqlite3_load_
2e150 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
2e160 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
2e170 65 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  empt to.**      
2e180 20 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d      fill *pzErrM
2e190 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65  sg with error me
2e1a0 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65  ssage text store
2e1b0 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  d in memory.**  
2e1c0 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64          obtained
2e1d0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2e1e0 61 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20  alloc()]. {END} 
2e1f0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
2e200 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2e210 20 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68    should free th
2e220 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c  is memory by cal
2e230 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
2e240 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ee()]..**.** {H1
2e250 32 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20  2606} Extension 
2e260 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20  loading must be 
2e270 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a  enabled using.**
2e280 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2e290 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2e2a0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f  xtension()] prio
2e2b0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  r to calling thi
2e2c0 73 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20  s API,.**       
2e2d0 20 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20     otherwise an 
2e2e0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
2e2f0 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  turned..*/.int s
2e300 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2e310 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
2e320 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
2e330 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
2e340 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
2e350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e360 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
2e370 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
2e380 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
2e390 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
2e3a0 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
2e3b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2e3c0 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
2e3d0 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
2e3e0 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
2e3f0 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
2e400 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
2e410 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
2e420 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
2e430 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
2e440 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2e450 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
2e460 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48  nsion Loading {H
2e470 31 32 36 32 30 7d 20 3c 53 32 30 35 30 30 3e 0a  12620} <S20500>.
2e480 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20  **.** So as not 
2e490 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79  to open security
2e4a0 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20   holes in older 
2e4b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
2e4c0 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61  t are.** unprepa
2e4d0 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68  red to deal with
2e4e0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
2e4f0 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61  ng, and as a mea
2e500 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a  ns of disabling.
2e510 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** extension loa
2e520 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75  ding while evalu
2e530 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72  ating user-enter
2e540 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c  ed SQL, the foll
2e550 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20  owing API.** is 
2e560 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e  provided to turn
2e570 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
2e580 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
2e590 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64  mechanism on and
2e5a0 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65   off..**.** Exte
2e5b0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
2e5c0 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
2e5d0 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
2e5e0 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 31  3..**.** {H12621
2e5f0 7d 20 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74  } Call the sqlit
2e600 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2e610 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69  xtension() routi
2e620 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ne with onoff==1
2e630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
2e640 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
2e650 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
2e660 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
2e670 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 20  ==0 to turn.**  
2e680 20 20 20 20 20 20 20 20 69 74 20 62 61 63 6b 20          it back 
2e690 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a  off again..**.**
2e6a0 20 7b 48 31 32 36 32 32 7d 20 45 78 74 65 6e 73   {H12622} Extens
2e6b0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f  ion loading is o
2e6c0 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ff by default..*
2e6d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2e6e0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
2e6f0 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
2e700 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
2e710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
2e720 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
2e730 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73 20 7b   An Extensions {
2e740 48 31 32 36 34 30 7d 20 3c 53 32 30 35 30 30 3e  H12640} <S20500>
2e750 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
2e760 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61  can be invoked a
2e770 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75  t program startu
2e780 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65  p in order to re
2e790 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72  gister.** one or
2e7a0 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79   more statically
2e7b0 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f   linked extensio
2e7c0 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  ns that will be 
2e7d0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20  available.** to 
2e7e0 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61 73  all new [databas
2e7f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20  e connections]. 
2e800 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  {END}.**.** This
2e810 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
2e820 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2e830 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e   extension in an
2e840 20 61 72 72 61 79 20 74 68 61 74 20 69 73 0a 2a   array that is.*
2e850 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
2e860 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2e870 29 5d 2e 20 20 49 66 20 79 6f 75 20 72 75 6e 20  )].  If you run 
2e880 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 63 68  a memory leak ch
2e890 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72  ecker.** on your
2e8a0 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74 20   program and it 
2e8b0 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20 62  reports a leak b
2e8c0 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 61  ecause of this a
2e8d0 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20  rray, invoke.** 
2e8e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61  [sqlite3_reset_a
2e8f0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
2e900 20 70 72 69 6f 72 20 74 6f 20 73 68 75 74 64 6f   prior to shutdo
2e910 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d  wn to free the m
2e920 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  emory..**.** {H1
2e930 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74  2641} This funct
2e940 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e  ion registers an
2e950 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79   extension entry
2e960 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a   point that is.*
2e970 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d  *          autom
2e980 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64  atically invoked
2e990 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20   whenever a new 
2e9a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2e9b0 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20  tion].**        
2e9c0 20 20 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e    is opened usin
2e9d0 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  g [sqlite3_open(
2e9e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2e9f0 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  n16()],.**      
2ea00 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2ea10 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
2ea20 2a 20 7b 48 31 32 36 34 32 7d 20 44 75 70 6c 69  * {H12642} Dupli
2ea30 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  cate extensions 
2ea40 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20  are detected so 
2ea50 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  calling this rou
2ea60 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tine.**         
2ea70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
2ea80 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78  with the same ex
2ea90 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c  tension is harml
2eaa0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ess..**.** {H126
2eab0 34 33 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65  43} This routine
2eac0 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65   stores a pointe
2ead0 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69  r to the extensi
2eae0 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a  on in an array.*
2eaf0 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
2eb00 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  is obtained from
2eb10 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2eb20 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ()]..**.** {H126
2eb30 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 78  44} Automatic ex
2eb40 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
2eb50 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
2eb60 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2eb70 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
2eb80 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
2eb90 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
2eba0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2ebb0 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
2ebc0 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20  tension Loading 
2ebd0 7b 48 31 32 36 36 30 7d 20 3c 53 32 30 35 30 30  {H12660} <S20500
2ebe0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
2ebf0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
2ec00 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
2ec10 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
2ec20 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73  ic.** extensions
2ec30 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75 6e 64 6f  . {END}  It undo
2ec40 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
2ec50 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73   all prior.** [s
2ec60 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
2ec70 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a  nsion()] calls..
2ec80 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31 7d 20 54  **.** {H12661} T
2ec90 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  his function dis
2eca0 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f  ables all previo
2ecb0 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a  usly registered.
2ecc0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
2ecd0 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
2ece0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 32 7d  ..**.** {H12662}
2ecf0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64   This function d
2ed00 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69  isables automati
2ed10 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20  c extensions in 
2ed20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  all threads..*/.
2ed30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2ed40 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
2ed50 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a  n(void);../*.***
2ed60 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
2ed70 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
2ed80 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
2ed90 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
2eda0 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  **.**.** The int
2edb0 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
2edc0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2edd0 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
2ede0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
2edf0 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
2ee00 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
2ee10 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
2ee20 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
2ee30 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
2ee40 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
2ee50 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
2ee60 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
2ee70 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
2ee80 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
2ee90 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
2eea0 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
2eeb0 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
2eec0 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
2eed0 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
2eee0 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
2eef0 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
2ef00 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
2ef10 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
2ef20 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
2ef30 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
2ef40 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
2ef50 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2ef60 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
2ef70 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
2ef80 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2ef90 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
2efa0 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
2efb0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2efc0 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
2efd0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
2efe0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2eff0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
2f000 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
2f010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
2f020 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a  irtual Table Obj
2f030 65 63 74 20 7b 48 31 38 30 30 30 7d 20 3c 53 32  ect {H18000} <S2
2f040 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0400>.** KEYWORD
2f050 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
2f060 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e {virtual table
2f070 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45   module}.** EXPE
2f080 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
2f090 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73  his structure, s
2f0a0 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20  ometimes called 
2f0b0 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62  a a "virtual tab
2f0c0 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20  le module", .** 
2f0d0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c  defines the impl
2f0e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20  ementation of a 
2f0f0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
2f100 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75  .  .** This stru
2f110 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d  cture consists m
2f120 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
2f130 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
2f140 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c  .**.** A virtual
2f150 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73   table module is
2f160 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c   created by fill
2f170 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74  ing in a persist
2f180 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20  ent.** instance 
2f190 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
2f1a0 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
2f1b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2f1c0 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b  instance.** to [
2f1d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
2f1e0 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
2f1f0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
2f200 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65  le_v2()]..** The
2f210 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65   registration re
2f220 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69  mains valid unti
2f230 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64  l it is replaced
2f240 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a   by a different.
2f250 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74  ** module or unt
2f260 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  il the [database
2f270 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f   connection] clo
2f280 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  ses.  The conten
2f290 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72  t.** of this str
2f2a0 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20  ucture must not 
2f2b0 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20  change while it 
2f2c0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
2f2d0 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61  th.** any databa
2f2e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
2f2f0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
2f300 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20  _module {.  int 
2f310 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
2f320 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74  (*xCreate)(sqlit
2f330 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
2f340 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2f350 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
2f360 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
2f370 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2f380 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
2f390 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
2f3a0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63  .  int (*xConnec
2f3b0 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  t)(sqlite3*, voi
2f3c0 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
2f3d0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
2f3e0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
2f3f0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
2f400 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
2f410 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
2f420 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
2f430 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c  *xBestIndex)(sql
2f440 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2f450 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  , sqlite3_index_
2f460 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  info*);.  int (*
2f470 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
2f480 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2f490 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74  );.  int (*xDest
2f4a0 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61  roy)(sqlite3_vta
2f4b0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
2f4c0 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
2f4d0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
2f4e0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2f4f0 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a  or **ppCursor);.
2f500 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
2f510 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2f520 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
2f530 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
2f540 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
2f550 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
2f560 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
2f570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
2f580 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
2f590 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20  value **argv);. 
2f5a0 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71   int (*xNext)(sq
2f5b0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2f5c0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f  r*);.  int (*xEo
2f5d0 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  f)(sqlite3_vtab_
2f5e0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
2f5f0 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
2f600 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
2f610 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2f620 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
2f630 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33  *xRowid)(sqlite3
2f640 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
2f650 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52  qlite3_int64 *pR
2f660 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  owid);.  int (*x
2f670 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f  Update)(sqlite3_
2f680 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c  vtab *, int, sql
2f690 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73  ite3_value **, s
2f6a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b  qlite3_int64 *);
2f6b0 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29  .  int (*xBegin)
2f6c0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2f6d0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2f6e0 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74  Sync)(sqlite3_vt
2f6f0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2f700 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c  t (*xCommit)(sql
2f710 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2f720 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c  );.  int (*xRoll
2f730 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74  back)(sqlite3_vt
2f740 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2f750 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f  t (*xFindFunctio
2f760 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
2f770 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67  *pVtab, int nArg
2f780 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2f790 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20  ame,.           
2f7a0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2f7b0 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69   (**pxFunc)(sqli
2f7c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2f7d0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2f7e0 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
2f7f0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a            void *
2f800 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28  *ppArg);.  int (
2f810 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
2f820 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63  3_vtab *pVtab, c
2f830 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29  onst char *zNew)
2f840 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ;.};../*.** CAPI
2f850 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
2f860 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66  ble Indexing Inf
2f870 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38 31 30 30  ormation {H18100
2f880 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45  } <S20400>.** KE
2f890 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
2f8a0 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58  index_info.** EX
2f8b0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
2f8c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64   The sqlite3_ind
2f8d0 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
2f8e0 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72  e and its substr
2f8f0 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20  uctures is used 
2f900 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72  to.** pass infor
2f910 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20  mation into and 
2f920 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c  receive the repl
2f930 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73  y from the [xBes
2f940 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f  tIndex].** metho
2f950 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  d of a [virtual 
2f960 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
2f970 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72  The fields under
2f980 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20   **Inputs** are 
2f990 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f  the.** inputs to
2f9a0 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
2f9b0 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20  are read-only.  
2f9c0 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72  xBestIndex inser
2f9d0 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74  ts its.** result
2f9e0 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74  s into the **Out
2f9f0 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a  puts** fields..*
2fa00 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72  *.** The aConstr
2fa10 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63  aint[] array rec
2fa20 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73  ords WHERE claus
2fa30 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66  e constraints of
2fa40 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a   the form:.**.**
2fa50 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20   <pre>column OP 
2fa60 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  expr</pre>.**.**
2fa70 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20   where OP is =, 
2fa80 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74  &lt;, &lt;=, &gt
2fa90 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20 20 54 68  ;, or &gt;=.  Th
2faa0 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65  e particular ope
2fab0 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72  rator is.** stor
2fac0 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  ed in aConstrain
2fad0 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64  t[].op.  The ind
2fae0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2faf0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a   is stored in.**
2fb00 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
2fb10 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72  Column.  aConstr
2fb20 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
2fb30 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
2fb40 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
2fb50 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
2fb60 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
2fb70 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
2fb80 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
2fb90 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
2fba0 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a   it cannot..**.*
2fbb0 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20  * The optimizer 
2fbc0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2fbd0 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
2fbe0 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
2fbf0 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
2fc00 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
2fc10 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74  lifications to t
2fc20 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
2fc30 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
2fc40 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
2fc50 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
2fc60 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
2fc70 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
2fc80 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  possible..** The
2fc90 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
2fca0 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74  rray only report
2fcb0 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  s WHERE clause t
2fcc0 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72  erms in the corr
2fcd0 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74  ect.** form that
2fce0 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61   refer to the pa
2fcf0 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
2fd00 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65   table being que
2fd10 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f  ried..**.** Info
2fd20 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
2fd30 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
2fd40 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  e is stored in a
2fd50 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61  OrderBy[]..** Ea
2fd60 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65  ch term of aOrde
2fd70 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f  rBy records a co
2fd80 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45  lumn of the ORDE
2fd90 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a  R BY clause..**.
2fda0 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64  ** The [xBestInd
2fdb0 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  ex] method must 
2fdc0 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74  fill aConstraint
2fdd0 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66  Usage[] with inf
2fde0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
2fdf0 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72  t what parameter
2fe00 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69  s to pass to xFi
2fe10 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e  lter.  If argvIn
2fe20 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68  dex>0 then.** th
2fe30 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
2fe40 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70  e of the corresp
2fe50 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69  onding aConstrai
2fe60 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65  nt[] is evaluate
2fe70 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73  d.** and becomes
2fe80 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74   the argvIndex-t
2fe90 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e  h entry in argv.
2fea0 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74    If aConstraint
2feb0 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
2fec0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
2fed0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
2fee0 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
2fef0 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
2ff00 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
2ff10 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
2ff20 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
2ff30 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
2ff40 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  e idxNum and idx
2ff50 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72  Ptr values are r
2ff60 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73  ecorded and pass
2ff70 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b  ed into the.** [
2ff80 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e  xFilter] method.
2ff90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2ffa0 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  e()] is used to 
2ffb0 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61  free idxPtr if a
2ffc0 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e  nd only iff.** n
2ffd0 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20  eedToFreeIdxPtr 
2ffe0 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  is true..**.** T
2fff0 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  he orderByConsum
30000 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75  ed means that ou
30010 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74  tput from [xFilt
30020 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c  er]/[xNext] will
30030 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65   occur in.** the
30040 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74   correct order t
30050 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52  o satisfy the OR
30060 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f  DER BY clause so
30070 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74   that no separat
30080 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65  e.** sorting ste
30090 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  p is required..*
300a0 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74  *.** The estimat
300b0 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20  edCost value is 
300c0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74  an estimate of t
300d0 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67  he cost of doing
300e0 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c   the.** particul
300f0 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75  ar lookup.  A fu
30100 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62  ll scan of a tab
30110 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65  le with N entrie
30120 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  s should have.**
30130 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41   a cost of N.  A
30140 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f   binary search o
30150 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65  f a table of N e
30160 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
30170 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20  ve a.** cost of 
30180 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f  approximately lo
30190 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  g(N)..*/.struct 
301a0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
301b0 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73  fo {.  /* Inputs
301c0 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74   */.  int nConst
301d0 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
301e0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e   /* Number of en
301f0 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72  tries in aConstr
30200 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74  aint */.  struct
30210 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
30220 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20  onstraint {.    
30230 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
30240 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
30250 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e  lumn on left-han
30260 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72  d side of constr
30270 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73  aint */.     uns
30280 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20  igned char op;  
30290 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72         /* Constr
302a0 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f  aint operator */
302b0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
302c0 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20  har usable;     
302d0 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20  /* True if this 
302e0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73  constraint is us
302f0 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74  able */.     int
30300 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20   iTermOffset;   
30310 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
30320 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73  nternally - xBes
30330 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67  tIndex should ig
30340 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  nore */.  } *aCo
30350 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
30360 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66       /* Table of
30370 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
30380 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69  nstraints */.  i
30390 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20  nt nOrderBy;    
303a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
303b0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
303c0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
303d0 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  use */.  struct 
303e0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72  sqlite3_index_or
303f0 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74  derby {.     int
30400 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
30410 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
30420 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20   number */.     
30430 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65  unsigned char de
30440 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  sc;       /* Tru
30450 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c  e for DESC.  Fal
30460 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20  se for ASC. */. 
30470 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20   } *aOrderBy;   
30480 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
30490 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
304a0 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75  se */.  /* Outpu
304b0 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  ts */.  struct s
304c0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
304d0 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a  straint_usage {.
304e0 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
304f0 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
30500 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e  if >0, constrain
30510 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67  t is part of arg
30520 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a  v to xFilter */.
30530 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
30540 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20  r omit;      /* 
30550 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65  Do not code a te
30560 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73  st for this cons
30570 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61  traint */.  } *a
30580 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b  ConstraintUsage;
30590 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20  .  int idxNum;  
305a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
305b0 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20   Number used to 
305c0 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64  identify the ind
305d0 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64  ex */.  char *id
305e0 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20  xStr;           
305f0 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f     /* String, po
30600 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20  ssibly obtained 
30610 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
30620 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65  loc */.  int nee
30630 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20  dToFreeIdxStr;  
30640 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53      /* Free idxS
30650 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  tr using sqlite3
30660 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20  _free() if true 
30670 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79  */.  int orderBy
30680 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20  Consumed;       
30690 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75  /* True if outpu
306a0 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64  t is already ord
306b0 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65  ered */.  double
306c0 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20   estimatedCost; 
306d0 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65       /* Estimate
306e0 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20  d cost of using 
306f0 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b  this index */.};
30700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30710 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
30720 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65  _EQ    2.#define
30730 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
30740 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34  NSTRAINT_GT    4
30750 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30760 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
30770 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65  _LE    8.#define
30780 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
30790 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31  NSTRAINT_LT    1
307a0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
307b0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
307c0 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69  T_GE    32.#defi
307d0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
307e0 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48  CONSTRAINT_MATCH
307f0 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   64../*.** CAPI3
30800 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
30810 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d  Virtual Table Im
30820 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31  plementation {H1
30830 38 32 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8200} <S20400>.*
30840 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
30850 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
30860 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67  e is used to reg
30870 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72  ister a new [vir
30880 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
30890 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d 6f 64 75  e] name..** Modu
308a0 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65  le names must be
308b0 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f   registered befo
308c0 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61  re.** creating a
308d0 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61   new [virtual ta
308e0 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d  ble] using the m
308f0 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65  odule, or before
30900 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65   using a.** pree
30910 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c  xisting [virtual
30920 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20   table] for the 
30930 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  module..**.** Th
30940 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73  e module name is
30950 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74   registered on t
30960 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
30970 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
30980 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
30990 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  st parameter.  T
309a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
309b0 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62  odule is given b
309c0 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64  y the .** second
309d0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
309e0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
309f0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
30a00 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
30a10 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76  tation of the [v
30a20 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
30a30 75 6c 65 5d 2e 20 20 20 54 68 65 20 66 6f 75 72  ule].   The four
30a40 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  th.** parameter 
30a50 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
30a60 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e  client data poin
30a70 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
30a80 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e  ed through.** in
30a90 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d  to the [xCreate]
30aa0 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20   and [xConnect] 
30ab0 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76  methods of the v
30ac0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
30ad0 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65  ule.** when a ne
30ae0 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  w virtual table 
30af0 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61  is be being crea
30b00 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c  ted or reinitial
30b10 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ized..**.** This
30b20 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 65   interface has e
30b30 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
30b40 65 66 66 65 63 74 20 61 73 20 63 61 6c 6c 69 6e  effect as callin
30b50 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
30b60 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
30b70 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 63 6c  ] with a NULL cl
30b80 69 65 6e 74 20 64 61 74 61 20 64 65 73 74 72 75  ient data destru
30b90 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ctor..*/.SQLITE_
30ba0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
30bb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30bc0 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65  module(.  sqlite
30bd0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
30be0 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
30bf0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
30c00 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
30c10 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
30c20 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
30c30 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
30c40 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
30c50 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
30c60 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f  e *p,   /* Metho
30c70 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
30c80 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c  e */.  void *pCl
30c90 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20  ientData        
30ca0 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
30cb0 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
30cc0 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  nnect */.);../*.
30cd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
30ce0 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20  ister A Virtual 
30cf0 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61  Table Implementa
30d00 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d 20 3c 53  tion {H18210} <S
30d10 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20400>.** EXPERI
30d20 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69  MENTAL.**.** Thi
30d30 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65  s routine is ide
30d40 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 5b 73  ntical to the [s
30d50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
30d60 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f 64 2c 0a  dule()] method,.
30d70 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
30d80 74 20 68 61 73 20 61 6e 20 65 78 74 72 61 20 70  t has an extra p
30d90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 70 65 63  arameter to spec
30da0 69 66 79 20 0a 2a 2a 20 61 20 64 65 73 74 72 75  ify .** a destru
30db0 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ctor function fo
30dc0 72 20 74 68 65 20 63 6c 69 65 6e 74 20 64 61 74  r the client dat
30dd0 61 20 70 6f 69 6e 74 65 72 2e 20 20 53 51 4c 69  a pointer.  SQLi
30de0 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b  te will.** invok
30df0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
30e00 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74   function (if it
30e10 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68   is not NULL) wh
30e20 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20  en SQLite.** no 
30e30 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65  longer needs the
30e40 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69   pClientData poi
30e50 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54  nter.  .*/.SQLIT
30e60 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
30e70 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
30e80 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
30e90 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
30ea0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
30eb0 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
30ec0 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
30ed0 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
30ee0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
30ef0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
30f00 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
30f10 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
30f20 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
30f30 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
30f40 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
30f50 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20   *pClientData,  
30f60 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
30f70 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
30f80 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
30f90 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
30fa0 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
30fb0 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
30fc0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
30fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30fe0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
30ff0 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 48  stance Object {H
31000 31 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18010} <S20400>.
31010 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
31020 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58 50  ite3_vtab.** EXP
31030 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
31040 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
31050 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
31060 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
31070 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f   a subclass.** o
31080 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
31090 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73  structure to des
310a0 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c  cribe a particul
310b0 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f  ar instance.** o
310c0 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
310d0 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62  able].  Each sub
310e0 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65  class will.** be
310f0 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65   tailored to the
31100 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
31110 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d  of the module im
31120 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a  plementation..**
31130 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20   The purpose of 
31140 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  this superclass 
31150 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72  is to define cer
31160 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74  tain fields that
31170 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74   are.** common t
31180 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70  o all module imp
31190 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a  lementations..**
311a0 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
311b0 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73  es methods can s
311c0 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  et an error mess
311d0 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67  age by assigning
311e0 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74   a.** string obt
311f0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
31200 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74  te3_mprintf()] t
31210 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20  o zErrMsg.  The 
31220 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a  method should.**
31230 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20   take care that 
31240 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67  any prior string
31250 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63   is freed by a c
31260 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
31270 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72  free()].** prior
31280 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20   to assigning a 
31290 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45  new string to zE
312a0 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 68  rrMsg.  After th
312b0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  e error message.
312c0 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20  ** is delivered 
312d0 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74  up to the client
312e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
312f0 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
31300 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
31310 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74  * freed by sqlit
31320 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68  e3_free() and th
31330 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20  e zErrMsg field 
31340 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a  will be zeroed..
31350 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
31360 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74  3_vtab {.  const
31370 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
31380 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68  *pModule;  /* Th
31390 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69  e module for thi
313a0 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  s virtual table 
313b0 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20  */.  int nRef;  
313c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
313d0 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45       /* NO LONGE
313e0 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72  R USED */.  char
313f0 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20   *zErrMsg;      
31400 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
31410 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f  rror message fro
31420 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
31430 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  f() */.  /* Virt
31440 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
31450 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
31460 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
31470 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
31480 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
31490 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
314a0 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63  ble Cursor Objec
314b0 74 20 20 7b 48 31 38 30 32 30 7d 20 3c 53 32 30  t  {H18020} <S20
314c0 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  400>.** KEYWORDS
314d0 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  : sqlite3_vtab_c
314e0 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74  ursor {virtual t
314f0 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 20  able cursor}.** 
31500 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
31510 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
31520 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
31530 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
31540 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
31550 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  f the.** followi
31560 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  ng structure to 
31570 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
31580 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
31590 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   the.** [virtual
315a0 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20   table] and are 
315b0 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
315c0 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
315d0 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
315e0 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
315f0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
31600 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70  lite3_module.xOp
31610 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68  en | xOpen] meth
31620 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
31630 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79   and are destroy
31640 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71  ed.** by the [sq
31650 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c  lite3_module.xCl
31660 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65  ose | xClose] me
31670 74 68 6f 64 2e 20 20 43 75 73 73 6f 72 73 20 61  thod.  Cussors a
31680 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  re used.** by th
31690 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e  e [xFilter], [xN
316a0 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78  ext], [xEof], [x
316b0 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52  Column], and [xR
316c0 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a  owid] methods.**
316d0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
316e0 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70   Each module imp
316f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
31700 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63   define.** the c
31710 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73  ontent of a curs
31720 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  or structure to 
31730 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65  suit its own nee
31740 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  ds..**.** This s
31750 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73  uperclass exists
31760 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66   in order to def
31770 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ine fields of th
31780 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a  e cursor that.**
31790 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61   are common to a
317a0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ll implementatio
317b0 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ns..*/.struct sq
317c0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
317d0 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74  r {.  sqlite3_vt
317e0 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20  ab *pVtab;      
317f0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
31800 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20   of this cursor 
31810 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
31820 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
31830 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
31840 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
31850 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
31860 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31870 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63  : Declare The Sc
31880 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61  hema Of A Virtua
31890 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30 7d  l Table {H18280}
318a0 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50   <S20400>.** EXP
318b0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
318c0 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  The [xCreate] an
318d0 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
318e0 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69  hods of a.** [vi
318f0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
31900 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e  le] call this in
31910 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65  terface.** to de
31920 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74  clare the format
31930 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20   (the names and 
31940 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65  datatypes of the
31950 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20   columns) of.** 
31960 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
31970 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e  es they implemen
31980 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  t..*/.SQLITE_EXP
31990 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
319a0 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
319b0 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ab(sqlite3*, con
319c0 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a  st char *zSQL);.
319d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
319e0 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63   Overload A Func
319f0 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75  tion For A Virtu
31a00 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 33 30 30  al Table {H18300
31a10 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58  } <S20400>.** EX
31a20 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
31a30 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
31a40 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65  can provide alte
31a50 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e  rnative implemen
31a60 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74  tations of funct
31a70 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ions.** using th
31a80 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e  e [xFindFunction
31a90 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
31aa0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
31ab0 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74  odule].  .** But
31ac0 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73   global versions
31ad0 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69   of those functi
31ae0 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73  ons.** must exis
31af0 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65  t in order to be
31b00 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a   overloaded..**.
31b10 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65  ** This API make
31b20 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20  s sure a global 
31b30 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e  version of a fun
31b40 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72  ction with a par
31b50 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20  ticular.** name 
31b60 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  and number of pa
31b70 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e  rameters exists.
31b80 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e    If no such fun
31b90 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20  ction exists.** 
31ba0 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20  before this API 
31bb0 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77  is called, a new
31bc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65   function is cre
31bd0 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65  ated.  The imple
31be0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
31bf0 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
31c00 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61   always causes a
31c10 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62  n exception to b
31c20 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a  e thrown.  So.**
31c30 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
31c40 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f  n is not good fo
31c50 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74  r anything by it
31c60 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a  self.  Its only.
31c70 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f  ** purpose is to
31c80 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65   be a placeholde
31c90 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  r function that 
31ca0 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  can be overloade
31cb0 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75  d.** by a [virtu
31cc0 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51  al table]..*/.SQ
31cd0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
31ce0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76  L int sqlite3_ov
31cf0 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28  erload_function(
31d00 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
31d10 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c  char *zFuncName,
31d20 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a   int nArg);../*.
31d30 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
31d40 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
31d50 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
31d60 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62  defined above (b
31d70 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63  ack up.** to a c
31d80 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c  omment remarkabl
31d90 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69  y similar to thi
31da0 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e  s one) is curren
31db0 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
31dc0 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
31dd0 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
31de0 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
31df0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
31e00 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
31e10 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
31e20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
31e30 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
31e40 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
31e50 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
31e60 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
31e70 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
31e80 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
31e90 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
31ea0 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
31eb0 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
31ec0 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
31ed0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a  his comment..**.
31ee0 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ****** EXPERIMEN
31ef0 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f  TAL - subject to
31f00 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20   change without 
31f10 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  notice *********
31f20 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  *****.*/../*.** 
31f30 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64  CAPI3REF: A Hand
31f40 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c  le To An Open BL
31f50 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33 30  OB {H17800} <S30
31f60 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  230>.** KEYWORDS
31f70 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20  : {BLOB handle} 
31f80 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a  {BLOB handles}.*
31f90 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
31fa0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
31fb0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
31fc0 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68  en BLOB on which
31fd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
31fe0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
31ff0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63  ntal BLOB I/O] c
32000 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e  an be performed.
32010 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74  .** Objects of t
32020 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65  his type are cre
32030 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
32040 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  _blob_open()].**
32050 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62   and destroyed b
32060 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
32070 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  close()]..** The
32080 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
32090 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
320a0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
320b0 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
320c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
320d0 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
320e0 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
320f0 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54  f the BLOB..** T
32100 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
32110 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
32120 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
32130 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  size of the BLOB
32140 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79   in bytes..*/.ty
32150 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
32160 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65  ite3_blob sqlite
32170 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_blob;../*.** C
32180 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20  API3REF: Open A 
32190 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65  BLOB For Increme
321a0 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31 30  ntal I/O {H17810
321b0 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a  } <S30230>.**.**
321c0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73   This interfaces
321d0 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68   opens a [BLOB h
321e0 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20  andle | handle] 
321f0 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61  to the BLOB loca
32200 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52  ted.** in row iR
32210 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75  ow, column zColu
32220 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65  mn, table zTable
32230 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62   in database zDb
32240 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f  ;.** in other wo
32250 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c  rds, the same BL
32260 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65  OB that would be
32270 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a   selected by:.**
32280 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
32290 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20   SELECT zColumn 
322a0 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20  FROM zDb.zTable 
322b0 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20  WHERE [rowid] = 
322c0 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20  iRow;.** </pre> 
322d0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
322e0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
322f0 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
32300 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  then the BLOB is
32310 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
32320 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63  .** and write ac
32330 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a  cess. If it is z
32340 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73  ero, the BLOB is
32350 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
32360 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e   access..**.** N
32370 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74  ote that the dat
32380 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f  abase name is no
32390 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74  t the filename t
323a0 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  hat contains.** 
323b0 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
323c0 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62   rather the symb
323d0 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65  olic name of the
323e0 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a   database that.*
323f0 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77 68  * is assigned wh
32400 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
32410 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69  is connected usi
32420 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20  ng [ATTACH]..** 
32430 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74  For the main dat
32440 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20  abase file, the 
32450 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
32460 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20   "main"..** For 
32470 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65  TEMP tables, the
32480 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
32490 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20  s "temp"..**.** 
324a0 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
324b0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
324c0 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20  ned and the new 
324d0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73  [BLOB handle] is
324e0 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a   written.** to *
324f0 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73  ppBlob. Otherwis
32500 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
32510 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
32520 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74  d *ppBlob is set
32530 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c  .** to be a null
32540 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 69   pointer..** Thi
32550 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  s function sets 
32560 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
32570 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20  nnection] error 
32580 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
32590 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76  .** accessible v
325a0 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
325b0 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ode()] and [sqli
325c0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e  te3_errmsg()] an
325d0 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e  d related.** fun
325e0 63 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74 68  ctions.  Note th
325f0 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76  at the *ppBlob v
32600 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79  ariable is alway
32610 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e  s initialized in
32620 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d   a.** way that m
32630 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20  akes it safe to 
32640 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
32650 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e  blob_close()] on
32660 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61   *ppBlob.** rega
32670 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
32680 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
32690 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
326a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
326b0 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68  ow that a BLOB h
326c0 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  andle points to 
326d0 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61  is modified by a
326e0 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b  n.** [UPDATE], [
326f0 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b  DELETE], or by [
32700 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64  ON CONFLICT] sid
32710 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65  e-effects.** the
32720 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  n the BLOB handl
32730 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22  e is marked as "
32740 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69  expired"..** Thi
32750 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79  s is true if any
32760 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
32770 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65  ow is changed, e
32780 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  ven a column.** 
32790 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f  other than the o
327a0 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  ne the BLOB hand
327b0 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a  le is open on..*
327c0 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * Calls to [sqli
327d0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
327e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
327f0 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a  ob_write()] for.
32800 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f  ** a expired BLO
32810 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69  B handle fail wi
32820 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64  th an return cod
32830 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
32840 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73 20  RT]..** Changes 
32850 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42  written into a B
32860 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65  LOB prior to the
32870 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61   BLOB expiring a
32880 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61  re not.** rollba
32890 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61  ck by the expira
328a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42  tion of the BLOB
328b0 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20  .  Such changes 
328c0 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a  will eventually.
328d0 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65  ** commit if the
328e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
328f0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
32900 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65 20  tion..**.** Use 
32910 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
32920 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
32930 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e  face to determin
32940 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  e the size of.**
32950 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62   the opened blob
32960 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 61  .  The size of a
32970 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65   blob may not be
32980 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73   changed by this
32990 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20  .** interface.  
329a0 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d  Use the [UPDATE]
329b0 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20   SQL command to 
329c0 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20  change the size 
329d0 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a  of a.** blob..**
329e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
329f0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
32a00 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
32a10 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
32a20 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
32a30 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  and the built-in
32a40 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20   [zeroblob] SQL 
32a50 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20  function can be 
32a60 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64  used, if desired
32a70 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61  ,.** to create a
32a80 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69  n empty, zero-fi
32a90 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69  lled blob in whi
32aa0 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ch to read or wr
32ab0 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69  ite using.** thi
32ac0 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
32ad0 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65  ** To avoid a re
32ae0 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65  source leak, eve
32af0 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  ry open [BLOB ha
32b00 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65  ndle] should eve
32b10 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65  ntually.** be re
32b20 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c  leased by a call
32b30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
32b40 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  b_close()]..**.*
32b50 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
32b60 2a 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48 31 37  ** [H17813] [H17
32b70 38 31 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b 48  814] [H17816] [H
32b80 31 37 38 31 39 5d 20 5b 48 31 37 38 32 31 5d 20  17819] [H17821] 
32b90 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a 69 6e 74 20  [H17824].*/.int 
32ba0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
32bb0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  n(.  sqlite3*,. 
32bc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
32bd0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
32be0 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20  zTable,.  const 
32bf0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20  char *zColumn,. 
32c00 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
32c10 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73  Row,.  int flags
32c20 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ,.  sqlite3_blob
32c30 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a   **ppBlob.);../*
32c40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
32c50 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c  ose A BLOB Handl
32c60 65 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30 32  e {H17830} <S302
32c70 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73  30>.**.** Closes
32c80 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
32c90 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c  andle]..**.** Cl
32ca0 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61  osing a BLOB sha
32cb0 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72  ll cause the cur
32cc0 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
32cd0 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66   to commit.** if
32ce0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74   there are no ot
32cf0 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65  her BLOBs, no pe
32d00 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73  nding prepared s
32d10 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74  tatements, and t
32d20 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
32d30 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20  onnection is in 
32d40 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  [autocommit mode
32d50 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72 69  ]..** If any wri
32d60 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f  tes were made to
32d70 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20   the BLOB, they 
32d80 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e  might be held in
32d90 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20   cache.** until 
32da0 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74  the close operat
32db0 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c  ion if they will
32dc0 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73   fit..**.** Clos
32dd0 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74  ing the BLOB oft
32de0 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68  en forces the ch
32df0 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20  anges.** out to 
32e00 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61  disk and so if a
32e10 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63  ny I/O errors oc
32e20 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c  cur, they will l
32e30 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61  ikely occur.** a
32e40 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20  t the time when 
32e50 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73  the BLOB is clos
32e60 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73 20  ed.  Any errors 
32e70 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e  that occur durin
32e80 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65  g.** closing are
32e90 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e   reported as a n
32ea0 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76  on-zero return v
32eb0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
32ec0 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75  BLOB is closed u
32ed0 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20  nconditionally. 
32ee0 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f   Even if this ro
32ef0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a  utine returns.**
32f00 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20   an error code, 
32f10 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c  the BLOB is stil
32f20 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  l closed..**.** 
32f30 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
32f40 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c  tine with a null
32f50 20 70 6f 69 6e 74 65 72 20 28 77 68 69 63 68 20   pointer (which 
32f60 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75  as would be retu
32f70 72 6e 65 64 0a 2a 2a 20 62 79 20 66 61 69 6c 65  rned.** by faile
32f80 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
32f90 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29  e3_blob_open()])
32fa0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
32fb0 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  o-op..**.** Requ
32fc0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
32fd0 37 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20 5b  7833] [H17836] [
32fe0 48 31 37 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73  H17839].*/.int s
32ff0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
33000 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
33010 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33020 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53  EF: Return The S
33030 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42  ize Of An Open B
33040 4c 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53 33  LOB {H17840} <S3
33050 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0230>.**.** Retu
33060 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20  rns the size in 
33070 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f  bytes of the BLO
33080 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  B accessible via
33090 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73   the .** success
330a0 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c  fully opened [BL
330b0 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74  OB handle] in it
330c0 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  s only argument.
330d0 20 20 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65    The.** increme
330e0 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f  ntal blob I/O ro
330f0 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20  utines can only 
33100 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74  read or overwrit
33110 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20  ing existing.** 
33120 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68  blob content; th
33130 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  ey cannot change
33140 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62   the size of a b
33150 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  lob..**.** This 
33160 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72  routine only wor
33170 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61  ks on a [BLOB ha
33180 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20  ndle] which has 
33190 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20  been created.** 
331a0 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  by a prior succe
331b0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
331c0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
331d0 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61  ()] and which ha
331e0 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c  s not.** been cl
331f0 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
33200 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20  _blob_close()]. 
33210 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68   Passing any oth
33220 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a  er pointer in.**
33230 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
33240 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
33250 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
33260 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ly undesirable b
33270 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 52  ehavior..**.** R
33280 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
33290 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74 20  [H17843].*/.int 
332a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
332b0 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  es(sqlite3_blob 
332c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
332d0 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46  REF: Read Data F
332e0 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  rom A BLOB Incre
332f0 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35 30  mentally {H17850
33300 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a  } <S30230>.**.**
33310 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
33320 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64  s used to read d
33330 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e  ata from an open
33340 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
33350 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d  nto a.** caller-
33360 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
33370 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   N bytes of data
33380 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
33390 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f   buffer Z.** fro
333a0 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c  m the open BLOB,
333b0 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
333c0 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
333d0 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66  ** If offset iOf
333e0 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
333f0 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n N bytes from t
33400 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c  he end of the BL
33410 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  OB,.** [SQLITE_E
33420 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
33430 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
33440 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72 20   read.  If N or 
33450 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65  iOffset is.** le
33460 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53  ss than zero, [S
33470 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
33480 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
33490 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a  data is read..**
334a0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
334b0 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65   blob (and hence
334c0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c   the maximum val
334d0 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29  ue of N+iOffset)
334e0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
334f0 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20  mined using the 
33500 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
33510 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
33520 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d  ..**.** An attem
33530 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20  pt to read from 
33540 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
33550 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
33560 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
33570 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
33580 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ABORT]..**.** On
33590 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
335a0 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
335b0 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61  .** Otherwise, a
335c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
335d0 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
335e0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
335f0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
33600 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
33610 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42  works on a [BLOB
33620 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68   handle] which h
33630 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a  as been created.
33640 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75  ** by a prior su
33650 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
33660 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
33670 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68  pen()] and which
33680 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e   has not.** been
33690 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69   closed by [sqli
336a0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
336b0 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20  ].  Passing any 
336c0 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e  other pointer in
336d0 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74  .** to this rout
336e0 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ine results in u
336f0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
33700 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
33710 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  e behavior..**.*
33720 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
33730 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
33740 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
33750 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38  ements:.** [H178
33760 35 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48 31  53] [H17856] [H1
33770 37 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20 5b  7859] [H17862] [
33780 48 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35 5d  H17863] [H17865]
33790 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e 74   [H17868].*/.int
337a0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
337b0 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ad(sqlite3_blob 
337c0 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20  *, void *Z, int 
337d0 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  N, int iOffset);
337e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
337f0 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74  : Write Data Int
33800 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
33810 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d 20  ntally {H17870} 
33820 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30230>.**.** T
33830 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
33840 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61  used to write da
33850 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20  ta into an open 
33860 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72  [BLOB handle] fr
33870 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  om a.** caller-s
33880 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
33890 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
338a0 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  are copied from 
338b0 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  the buffer Z.** 
338c0 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c  into the open BL
338d0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
338e0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
338f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42 4c  **.** If the [BL
33900 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65  OB handle] passe
33910 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
33920 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20  rgument was not 
33930 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72  opened for.** wr
33940 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73  iting (the flags
33950 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
33960 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
33970 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a  ()] was zero),.*
33980 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * this function 
33990 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
339a0 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a  READONLY]..**.**
339b0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   This function m
339c0 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74  ay only modify t
339d0 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
339e0 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a  he BLOB; it is.*
339f0 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  * not possible t
33a00 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73  o increase the s
33a10 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73  ize of a BLOB us
33a20 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a  ing this API..**
33a30 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73   If offset iOffs
33a40 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  et is less than 
33a50 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65  N bytes from the
33a60 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42   end of the BLOB
33a70 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
33a80 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
33a90 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
33aa0 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69 73  ritten.  If N is
33ab0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
33ac0 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ro [SQLITE_ERROR
33ad0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
33ae0 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
33af0 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a  tten..** The siz
33b00 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61  e of the BLOB (a
33b10 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78  nd hence the max
33b20 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b  imum value of N+
33b30 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20  iOffset).** can 
33b40 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
33b50 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
33b60 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
33b70 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
33b80 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72  An attempt to wr
33b90 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65  ite to an expire
33ba0 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  d [BLOB handle] 
33bb0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a  fails with an.**
33bc0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
33bd0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20  SQLITE_ABORT].  
33be0 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42 4c  Writes to the BL
33bf0 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65 64  OB that occurred
33c00 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
33c10 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78 70  BLOB handle] exp
33c20 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c  ired are not rol
33c30 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 0a  led back by the.
33c40 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  ** expiration of
33c50 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f   the handle, tho
33c60 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
33c70 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67 68  ose changes migh
33c80 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20 6f  t.** have been o
33c90 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
33ca0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
33cb0 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c 4f   expired the BLO
33cc0 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62  B handle.** or b
33cd0 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e 64  y other independ
33ce0 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  ent statements..
33cf0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
33d00 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  , SQLITE_OK is r
33d10 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65  eturned..** Othe
33d20 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f  rwise, an  [erro
33d30 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65  r code] or an [e
33d40 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
33d50 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
33d60 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
33d70 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
33d80 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
33d90 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
33da0 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
33db0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
33dc0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
33dd0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
33de0 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
33df0 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
33e00 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
33e10 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
33e20 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
33e30 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
33e40 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
33e50 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
33e60 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
33e70 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
33e80 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ior..**.** See a
33e90 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  lso: [sqlite3_bl
33ea0 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a 2a  ob_read()]..**.*
33eb0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
33ec0 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31 37  ** [H17873] [H17
33ed0 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b 48  874] [H17875] [H
33ee0 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d 20  17876] [H17877] 
33ef0 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38 32  [H17879] [H17882
33f00 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b 48  ] [H17885].** [H
33f10 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71  17888].*/.int sq
33f20 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
33f30 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
33f40 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
33f50 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
33f60 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
33f70 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69  3REF: Virtual Fi
33f80 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
33f90 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30 31  s {H11200} <S201
33fa0 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74  00>.**.** A virt
33fb0 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28  ual filesystem (
33fc0 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69  VFS) is an [sqli
33fd0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a  te3_vfs] object.
33fe0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75  ** that SQLite u
33ff0 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a  ses to interact.
34000 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65  ** with the unde
34010 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
34020 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53   system.  Most S
34030 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d  QLite builds com
34040 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67  e with a.** sing
34050 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74  le default VFS t
34060 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61  hat is appropria
34070 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20  te for the host 
34080 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77  computer..** New
34090 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65   VFSes can be re
340a0 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69  gistered and exi
340b0 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20  sting VFSes can 
340c0 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e  be unregistered.
340d0 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
340e0 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  g interfaces are
340f0 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a   provided..**.**
34100 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   The sqlite3_vfs
34110 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63  _find() interfac
34120 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
34130 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76  ter to a VFS giv
34140 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20  en its name..** 
34150 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
34160 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d  ensitive..** Nam
34170 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  es are zero-term
34180 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
34190 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65 72  ings..** If ther
341a0 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61  e is no match, a
341b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
341c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
341d0 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c   zVfsName is NUL
341e0 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  L then the defau
341f0 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72 6e  lt VFS is return
34200 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46  ed..**.** New VF
34210 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72  Ses are register
34220 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f  ed with sqlite3_
34230 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a  vfs_register()..
34240 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53 20  ** Each new VFS 
34250 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
34260 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
34270 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
34280 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65  set..** The same
34290 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69   VFS can be regi
342a0 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
342b0 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e  times without in
342c0 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65  jury..** To make
342d0 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53   an existing VFS
342e0 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c   into the defaul
342f0 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20  t VFS, register 
34300 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68  it again.** with
34310 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
34320 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20  ag set.  If two 
34330 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20  different VFSes 
34340 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65  with the.** same
34350 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74   name are regist
34360 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69  ered, the behavi
34370 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
34380 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73    If a.** VFS is
34390 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
343a0 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20   a name that is 
343b0 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
343c0 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e   string,.** then
343d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
343e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
343f0 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 56  * Unregister a V
34400 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69  FS with the sqli
34410 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
34420 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
34430 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 6c  ** If the defaul
34440 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73  t VFS is unregis
34450 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56  tered, another V
34460 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a  FS is chosen as.
34470 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20  ** the default. 
34480 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20   The choice for 
34490 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61  the new VFS is a
344a0 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
344b0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
344c0 20 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 32 30   [H11203] [H1120
344d0 36 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 31 31  6] [H11209] [H11
344e0 32 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b 48  212] [H11215] [H
344f0 31 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 74 65  11218].*/.sqlite
34500 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
34510 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
34520 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69  ar *zVfsName);.i
34530 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  nt sqlite3_vfs_r
34540 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
34550 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66  vfs*, int makeDf
34560 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  lt);.int sqlite3
34570 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
34580 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a  sqlite3_vfs*);..
34590 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
345a0 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30 30 7d  Mutexes {H17000}
345b0 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
345c0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
345d0 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
345e0 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a  nes for thread.*
345f0 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  * synchronizatio
34600 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61  n. Though they a
34610 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
34620 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
34630 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20  by SQLite, code 
34640 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
34650 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  st SQLite is.** 
34660 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65  permitted to use
34670 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
34680 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
34690 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  e SQLite source 
346a0 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75  code contains mu
346b0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
346c0 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65  ations.** of the
346d0 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  se mutex routine
346e0 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61  s.  An appropria
346f0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  te implementatio
34700 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64  n.** is selected
34710 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61   automatically a
34720 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20  t compile-time. 
34730 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a   The following.*
34740 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
34750 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
34760 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  in the SQLite co
34770 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  re:.**.** <ul>.*
34780 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
34790 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69  MUTEX_OS2.** <li
347a0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
347b0 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e  _PTHREAD.** <li>
347c0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
347d0 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  W32.** <li>   SQ
347e0 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a  LITE_MUTEX_NOOP.
347f0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
34800 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
34810 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74  NOOP implementat
34820 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20  ion is a set of 
34830 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74  routines.** that
34840 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f   does no real lo
34850 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70  cking and is app
34860 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
34870 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d   in.** a single-
34880 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
34890 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54  tion.  The SQLIT
348a0 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20  E_MUTEX_OS2,.** 
348b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
348c0 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45  READ, and SQLITE
348d0 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65  _MUTEX_W32 imple
348e0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
348f0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  e appropriate fo
34900 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55  r use on OS/2, U
34910 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73  nix, and Windows
34920 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74  ..**.** If SQLit
34930 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
34940 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55  th the SQLITE_MU
34950 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72  TEX_APPDEF prepr
34960 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f  ocessor.** macro
34970 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22   defined (with "
34980 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41  -DSQLITE_MUTEX_A
34990 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20  PPDEF=1"), then 
349a0 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  no mutex.** impl
349b0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e  ementation is in
349c0 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20  cluded with the 
349d0 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73  library. In this
349e0 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70   case the.** app
349f0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
34a00 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75  pply a custom mu
34a10 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
34a20 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  on using the.** 
34a30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
34a40 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20  UTEX] option of 
34a50 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  the sqlite3_conf
34a60 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ig() function.**
34a70 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20   before calling 
34a80 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
34a90 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65  ze() or any othe
34aa0 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33  r public sqlite3
34ab0 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  _.** function th
34ac0 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  at calls sqlite3
34ad0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
34ae0 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54 68  *.** {H17011} Th
34af0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
34b00 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
34b10 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a  allocates a new.
34b20 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74  ** mutex and ret
34b30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
34b40 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20 49  o it. {H17012} I
34b50 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  f it returns NUL
34b60 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20  L.** that means 
34b70 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75  that a mutex cou
34b80 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61  ld not be alloca
34b90 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53 51  ted. {H17013} SQ
34ba0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77  Lite.** will unw
34bb0 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e  ind its stack an
34bc0 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
34bd0 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65 20  r. {H17014} The 
34be0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
34bf0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
34c00 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74  oc() is one of t
34c10 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
34c20 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  stants:.**.** <u
34c30 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
34c40 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
34c50 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
34c60 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
34c70 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
34c80 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
34c90 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  R.** <li>  SQLIT
34ca0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
34cb0 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  EM.** <li>  SQLI
34cc0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
34cd0 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  MEM2.** <li>  SQ
34ce0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
34cf0 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20  C_PRNG.** <li>  
34d00 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
34d10 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20  TIC_LRU.** <li> 
34d20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
34d30 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75  ATIC_LRU2.** </u
34d40 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 35  l>.**.** {H17015
34d50 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20  } The first two 
34d60 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20  constants cause 
34d70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
34d80 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a  loc() to create.
34d90 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20  ** a new mutex. 
34da0 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69   The new mutex i
34db0 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e  s recursive when
34dc0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
34dd0 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73  CURSIVE.** is us
34de0 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73  ed but not neces
34df0 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53  sarily so when S
34e00 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
34e10 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a   is used. {END}.
34e20 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70  ** The mutex imp
34e30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73  lementation does
34e40 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b   not need to mak
34e50 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  e a distinction.
34e60 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
34e70 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
34e80 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  E and SQLITE_MUT
34e90 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f  EX_FAST if it do
34ea0 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
34eb0 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75 74  o.  {H17016} But
34ec0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
34ed0 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75  y request a recu
34ee0 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a  rsive mutex in.*
34ef0 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74  * cases where it
34f00 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e   really needs on
34f10 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66  e.  {END} If a f
34f20 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
34f30 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
34f40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
34f50 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
34f60 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
34f70 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
34f80 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
34f90 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
34fa0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
34fb0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
34fc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37 7d  ..**.** {H17017}
34fd0 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77   The other allow
34fe0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  ed parameters to
34ff0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
35000 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75  lloc() each retu
35010 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  rn.** a pointer 
35020 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65  to a static pree
35030 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b  xisting mutex. {
35040 45 4e 44 7d 20 20 53 69 78 20 73 74 61 74 69 63  END}  Six static
35050 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20   mutexes are.** 
35060 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72  used by the curr
35070 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  ent version of S
35080 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76  QLite.  Future v
35090 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
350a0 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64  e.** may add add
350b0 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d  itional static m
350c0 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20  utexes.  Static 
350d0 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20  mutexes are for 
350e0 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
350f0 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20  by SQLite only. 
35100 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
35110 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75  at use SQLite mu
35120 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  texes should.** 
35130 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e  use only the dyn
35140 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74  amic mutexes ret
35150 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f  urned by SQLITE_
35160 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a  MUTEX_FAST or.**
35170 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
35180 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b  CURSIVE..**.** {
35190 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68 61  H17018} Note tha
351a0 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20  t if one of the 
351b0 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61  dynamic mutex pa
351c0 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45  rameters (SQLITE
351d0 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f  _MUTEX_FAST.** o
351e0 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  r SQLITE_MUTEX_R
351f0 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65  ECURSIVE) is use
35200 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  d then sqlite3_m
35210 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20  utex_alloc().** 
35220 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72  returns a differ
35230 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65  ent mutex on eve
35240 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 30 33  ry call.  {H1703
35250 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20 73  4} But for the s
35260 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74  tatic.** mutex t
35270 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d  ypes, the same m
35280 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64  utex is returned
35290 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74   on every call t
352a0 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73  hat has.** the s
352b0 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e  ame type number.
352c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 7d 20  .**.** {H17019} 
352d0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
352e0 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  x_free() routine
352f0 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70   deallocates a p
35300 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c  reviously.** all
35310 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d  ocated dynamic m
35320 75 74 65 78 2e 20 7b 48 31 37 30 32 30 7d 20 53  utex. {H17020} S
35330 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 6c  QLite is careful
35340 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65   to deallocate e
35350 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20  very.** dynamic 
35360 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61 6c  mutex that it al
35370 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 32 31  locates. {A17021
35380 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  } The dynamic mu
35390 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62  texes must not b
353a0 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e  e in.** use when
353b0 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f   they are deallo
353c0 63 61 74 65 64 2e 20 7b 41 31 37 30 32 32 7d 20  cated. {A17022} 
353d0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65  Attempting to de
353e0 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69  allocate a stati
353f0 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c  c.** mutex resul
35400 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
35410 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 30 32  behavior. {H1702
35420 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20  3} SQLite never 
35430 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61  deallocates.** a
35440 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 7b   static mutex. {
35450 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  END}.**.** The s
35460 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
35470 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  er() and sqlite3
35480 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75  _mutex_try() rou
35490 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a  tines attempt.**
354a0 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65   to enter a mute
354b0 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 20 61  x. {H17024} If a
354c0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73  nother thread is
354d0 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20   already within 
354e0 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71  the mutex,.** sq
354f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
35500 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61  r() will block a
35510 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
35520 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75  _try() will retu
35530 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  rn.** SQLITE_BUS
35540 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 68 65  Y. {H17025}  The
35550 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
35560 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ry() interface r
35570 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
35580 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65  K].** upon succe
35590 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b 48  ssful entry.  {H
355a0 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73 20 63  17026} Mutexes c
355b0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
355c0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
355d0 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e  URSIVE can be en
355e0 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
355f0 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65  imes by the same
35600 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 31 37   thread..** {H17
35610 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63 61 73  027} In such cas
35620 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78  es the,.** mutex
35630 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20   must be exited 
35640 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20  an equal number 
35650 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20  of times before 
35660 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
35670 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b 41  * can enter.  {A
35680 31 37 30 32 38 7d 20 49 66 20 74 68 65 20 73 61  17028} If the sa
35690 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73 20  me thread tries 
356a0 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68  to enter any oth
356b0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75  er.** kind of mu
356c0 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  tex more than on
356d0 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ce, the behavior
356e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
356f0 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 4c 69 74  * {H17029} SQLit
35700 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68  e will never exh
35710 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68  ibit.** such beh
35720 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e  avior in its own
35730 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e   use of mutexes.
35740 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73 74  .**.** Some syst
35750 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ems (for example
35760 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f  , Windows 95) do
35770 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65   not support the
35780 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d   operation.** im
35790 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c  plemented by sql
357a0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
357b0 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74  .  On those syst
357c0 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  ems, sqlite3_mut
357d0 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c  ex_try().** will
357e0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53   always return S
357f0 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 48 31  QLITE_BUSY.  {H1
35800 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74 65  7030} The SQLite
35810 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20   core only ever 
35820 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  uses.** sqlite3_
35830 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61  mutex_try() as a
35840 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73  n optimization s
35850 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74  o this is accept
35860 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a  able behavior..*
35870 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 54 68  *.** {H17031} Th
35880 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
35890 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20  leave() routine 
358a0 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68  exits a mutex th
358b0 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  at was.** previo
358c0 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20  usly entered by 
358d0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
358e0 20 20 7b 41 31 37 30 33 32 7d 20 54 68 65 20 62    {A17032} The b
358f0 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
35900 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d  defined if the m
35910 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72  utex is not curr
35920 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ently entered by
35930 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20   the.** calling 
35940 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74  thread or is not
35950 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63   currently alloc
35960 61 74 65 64 2e 20 20 7b 48 31 37 30 33 33 7d 20  ated.  {H17033} 
35970 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e  SQLite will.** n
35980 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e 20  ever do either. 
35990 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
359a0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
359b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
359c0 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75  er(), sqlite3_mu
359d0 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a  tex_try(), or.**
359e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c   sqlite3_mutex_l
359f0 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c  eave() is a NULL
35a00 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61   pointer, then a
35a10 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  ll three routine
35a20 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e  s.** behave as n
35a30 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  o-ops..**.** See
35a40 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
35a50 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e  mutex_held()] an
35a60 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d [sqlite3_mutex
35a70 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a  _notheld()]..*/.
35a80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73  sqlite3_mutex *s
35a90 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
35aa0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  oc(int);.void sq
35ab0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
35ac0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
35ad0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
35ae0 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74  utex_enter(sqlit
35af0 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
35b00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
35b10 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  y(sqlite3_mutex*
35b20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35b30 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69  mutex_leave(sqli
35b40 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a  te3_mutex*);../*
35b50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
35b60 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  tex Methods Obje
35b70 63 74 20 7b 48 31 37 31 32 30 7d 20 3c 53 32 30  ct {H17120} <S20
35b80 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  130>.** EXPERIME
35b90 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  NTAL.**.** An in
35ba0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
35bb0 74 72 75 63 74 75 72 65 20 64 65 66 69 6e 65 73  tructure defines
35bc0 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72   the low-level r
35bd0 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20  outines.** used 
35be0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20  to allocate and 
35bf0 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a  use mutexes..**.
35c00 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20  ** Usually, the 
35c10 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d  default mutex im
35c20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72  plementations pr
35c30 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 74 65  ovided by SQLite
35c40 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65   are.** sufficie
35c50 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  nt, however the 
35c60 75 73 65 72 20 68 61 73 20 74 68 65 20 6f 70 74  user has the opt
35c70 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74  ion of substitut
35c80 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20  ing a custom.** 
35c90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
35ca0 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64  or specialized d
35cb0 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79  eployments or sy
35cc0 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20  stems for which 
35cd0 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e  SQLite.** does n
35ce0 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 75 69  ot provide a sui
35cf0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
35d00 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61  tion. In this ca
35d10 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20  se, the user.** 
35d20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75  creates and popu
35d30 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63  lates an instanc
35d40 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
35d50 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74  ure to pass.** t
35d60 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
35d70 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68  () along with th
35d80 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
35d90 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a  _MUTEX] option..
35da0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  ** Additionally,
35db0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
35dc0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  this structure c
35dd0 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61 6e  an be used as an
35de0 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61  .** output varia
35df0 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e  ble when queryin
35e00 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72  g the system for
35e10 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74   the current mut
35e20 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
35e30 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20  tion, using the 
35e40 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
35e50 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e  ETMUTEX] option.
35e60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65  .**.** The xMute
35e70 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66  xInit method def
35e80 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72  ined by this str
35e90 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65  ucture is invoke
35ea0 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
35eb0 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a  system initializ
35ec0 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c  ation by the sql
35ed0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
35ee0 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b  ) function..** {
35ef0 48 31 37 30 30 31 7d 20 54 68 65 20 78 4d 75 74  H17001} The xMut
35f00 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 73  exInit routine s
35f10 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  hall be called b
35f20 79 20 53 51 4c 69 74 65 20 6f 6e 63 65 20 66 6f  y SQLite once fo
35f30 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74  r each.** effect
35f40 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ive call to [sql
35f50 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
35f60 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  )]..**.** The xM
35f70 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64  utexEnd method d
35f80 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
35f90 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f  tructure is invo
35fa0 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ked as.** part o
35fb0 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77  f system shutdow
35fc0 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  n by the sqlite3
35fd0 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63  _shutdown() func
35fe0 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70  tion. The.** imp
35ff0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
36000 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78  his method is ex
36010 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73  pected to releas
36020 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e  e all outstandin
36030 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f  g.** resources o
36040 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d  btained by the m
36050 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70  utex methods imp
36060 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70  lementation, esp
36070 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65  ecially.** those
36080 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65   obtained by the
36090 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68   xMutexInit meth
360a0 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20 54 68 65  od. {H17003} The
360b0 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20   xMutexEnd().** 
360c0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
360d0 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  be invoked once 
360e0 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  for each call to
360f0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
36100 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  wn()]..**.** The
36110 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e   remaining seven
36120 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64   methods defined
36130 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75   by this structu
36140 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c  re (xMutexAlloc,
36150 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20  .** xMutexFree, 
36160 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75  xMutexEnter, xMu
36170 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65  texTry, xMutexLe
36180 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20  ave, xMutexHeld 
36190 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74  and.** xMutexNot
361a0 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20  held) implement 
361b0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  the following in
361c0 74 65 72 66 61 63 65 73 20 28 72 65 73 70 65 63  terfaces (respec
361d0 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c  tively):.**.** <
361e0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  ul>.**   <li>  [
361f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
36200 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  loc()] </li>.** 
36210 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
36220 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c  _mutex_free()] <
36230 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
36240 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
36250 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  nter()] </li>.**
36260 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
36270 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c  3_mutex_try()] <
36280 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
36290 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
362a0 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  eave()] </li>.**
362b0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
362c0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20  3_mutex_held()] 
362d0 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
362e0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
362f0 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e  notheld()] </li>
36300 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
36310 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
36320 6e 63 65 20 69 73 20 74 68 61 74 20 74 68 65 20  nce is that the 
36330 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58  public sqlite3_X
36340 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75  XX functions enu
36350 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65  merated.** above
36360 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
36370 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73   any invocations
36380 20 74 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c   that pass a NUL
36390 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  L pointer instea
363a0 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20  d.** of a valid 
363b0 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68  mutex handle. Th
363c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
363d0 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73  s of the methods
363e0 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74   defined.** by t
363f0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61 72  his structure ar
36400 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  e not required t
36410 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61  o handle this ca
36420 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a  se, the results.
36430 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20  ** of passing a 
36440 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73  NULL pointer ins
36450 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20  tead of a valid 
36460 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65  mutex handle are
36470 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69   undefined.** (i
36480 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65 70 74  .e. it is accept
36490 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20  able to provide 
364a0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
364b0 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c 74 73  n that segfaults
364c0 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73   if.** it is pas
364d0 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  sed a NULL point
364e0 65 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  er)..**.** The x
364f0 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68  MutexInit() meth
36500 6f 64 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  od must be threa
36510 64 73 61 66 65 2e 20 20 49 74 20 6d 75 73 74 20  dsafe.  It must 
36520 62 65 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a  be harmless to.*
36530 2a 20 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49  * invoke xMutexI
36540 6e 69 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69  nit() mutiple ti
36550 6d 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  mes within the s
36560 61 6d 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20  ame process and 
36570 77 69 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72  without.** inter
36580 76 65 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20  vening calls to 
36590 78 4d 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65  xMutexEnd().  Se
365a0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
365b0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
365c0 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73  xMutexInit() mus
365d0 74 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  t be no-ops..**.
365e0 2a 2a 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20  ** xMutexInit() 
365f0 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c  must not use SQL
36600 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ite memory alloc
36610 61 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f  ation ([sqlite3_
36620 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64  malloc()].** and
36630 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 73 29   its associates)
36640 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d  .  Similarly, xM
36650 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74  utexAlloc() must
36660 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20   not use SQLite 
36670 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
36680 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69  tion for a stati
36690 63 20 6d 75 74 65 78 2e 20 20 48 6f 77 65 76 65  c mutex.  Howeve
366a0 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20  r xMutexAlloc() 
366b0 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a  may use SQLite.*
366c0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
366d0 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f  ion for a fast o
366e0 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  r recursive mute
366f0 78 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  x..**.** SQLite 
36700 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
36710 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74 68  xMutexEnd() meth
36720 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  od when [sqlite3
36730 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a  _shutdown()] is.
36740 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f  ** called, but o
36750 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f 72  nly if the prior
36760 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49   call to xMutexI
36770 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c  nit returned SQL
36780 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d  ITE_OK..** If xM
36790 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20 69  utexInit fails i
367a0 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69 73  n any way, it is
367b0 20 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c 65   expected to cle
367c0 61 6e 20 75 70 20 61 66 74 65 72 20 69 74 73 65  an up after itse
367d0 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72  lf.** prior to r
367e0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70  eturning..*/.typ
367f0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
36800 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
36810 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  s sqlite3_mutex_
36820 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
36830 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
36840 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a  thods {.  int (*
36850 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64  xMutexInit)(void
36860 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
36870 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73  xEnd)(void);.  s
36880 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a  qlite3_mutex *(*
36890 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74  xMutexAlloc)(int
368a0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74  );.  void (*xMut
368b0 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f  exFree)(sqlite3_
368c0 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64  mutex *);.  void
368d0 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28   (*xMutexEnter)(
368e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
368f0 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
36900 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  Try)(sqlite3_mut
36910 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a  ex *);.  void (*
36920 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c  xMutexLeave)(sql
36930 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20  ite3_mutex *);. 
36940 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c   int (*xMutexHel
36950 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d)(sqlite3_mutex
36960 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75   *);.  int (*xMu
36970 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69  texNotheld)(sqli
36980 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b  te3_mutex *);.};
36990 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
369a0 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 61  : Mutex Verifica
369b0 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48  tion Routines {H
369c0 31 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e 20  17080} <S20130> 
369d0 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30800>.**.** T
369e0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
369f0 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c 69  _held() and sqli
36a00 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
36a10 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  d() routines.** 
36a20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
36a30 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 65   use inside asse
36a40 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 2e  rt() statements.
36a50 20 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53 51   {H17081} The SQ
36a60 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76  Lite core.** nev
36a70 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  er uses these ro
36a80 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e  utines except in
36a90 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29  side an assert()
36aa0 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e   and application
36ab0 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64  s.** are advised
36ac0 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c   to follow the l
36ad0 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e  ead of the core.
36ae0 20 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20 63    {H17082} The c
36af0 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76  ore only.** prov
36b00 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ides implementat
36b10 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72  ions for these r
36b20 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20  outines when it 
36b30 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
36b40 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ith the SQLITE_D
36b50 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 37  EBUG flag.  {A17
36b60 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75  087} External mu
36b70 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
36b80 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20  ons.** are only 
36b90 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76  required to prov
36ba0 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ide these routin
36bb0 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45 42  es if SQLITE_DEB
36bc0 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64  UG is.** defined
36bd0 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20 69   and if NDEBUG i
36be0 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a  s not defined..*
36bf0 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 68  *.** {H17083} Th
36c00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  ese routines sho
36c10 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20  uld return true 
36c20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20  if the mutex in 
36c30 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a  their argument.*
36c40 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74  * is held or not
36c50 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76   held, respectiv
36c60 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c  ely, by the call
36c70 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  ing thread..**.*
36c80 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69  * {X17084} The i
36c90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
36ca0 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f   not required to
36cb0 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f   provided versio
36cc0 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72  ns of these.** r
36cd0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 74  outines that act
36ce0 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74  ually work. If t
36cf0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
36d00 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69  n does not provi
36d10 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65  de working.** ve
36d20 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20  rsions of these 
36d30 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f  routines, it sho
36d40 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f  uld at least pro
36d50 76 69 64 65 20 73 74 75 62 73 20 74 68 61 74 20  vide stubs that 
36d60 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e  always.** return
36d70 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e   true so that on
36d80 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73  e does not get s
36d90 70 75 72 69 6f 75 73 20 61 73 73 65 72 74 69 6f  purious assertio
36da0 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a  n failures..**.*
36db0 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74 68  * {H17085} If th
36dc0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
36dd0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
36de0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
36df0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65  nter then.** the
36e00 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
36e10 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d  return 1.  {END}
36e20 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e   This seems coun
36e30 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69  ter-intuitive si
36e40 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74  nce.** clearly t
36e50 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20  he mutex cannot 
36e60 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f  be held if it do
36e70 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42  es not exist.  B
36e80 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65  ut the.** the re
36e90 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64  ason the mutex d
36ea0 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73  oes not exist is
36eb0 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69   because the bui
36ec0 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69  ld is not.** usi
36ed0 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64  ng mutexes.  And
36ee0 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20   we do not want 
36ef0 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e  the assert() con
36f00 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
36f10 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  all to sqlite3_m
36f20 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66  utex_held() to f
36f30 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65  ail, so a non-ze
36f40 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20  ro return is.** 
36f50 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
36f60 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 48  thing to do.  {H
36f70 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74  17086} The sqlit
36f80 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
36f90 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
36fa0 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75  should also retu
36fb0 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20  rn 1 when given 
36fc0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
36fd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  */.int sqlite3_m
36fe0 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65  utex_held(sqlite
36ff0 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
37000 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
37010 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
37020 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ex*);../*.** CAP
37030 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70  I3REF: Mutex Typ
37040 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 37  es {H17001} <H17
37050 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  000>.**.** The [
37060 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
37070 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65  loc()] interface
37080 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
37090 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63  argument.** whic
370a0 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  h is one of thes
370b0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
370c0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nts..**.** The s
370d0 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 74  et of static mut
370e0 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 20  exes may change 
370f0 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 20  from one SQLite 
37100 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a 2a  release to the.*
37110 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
37120 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 72  tions that overr
37130 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  ide the built-in
37140 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 73   mutex logic mus
37150 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  t be.** prepared
37160 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 20   to accommodate 
37170 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69  additional stati
37180 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 64  c mutexes..*/.#d
37190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
371a0 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20  EX_FAST         
371b0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
371c0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
371d0 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64  SIVE        1.#d
371e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
371f0 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
37200 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
37210 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
37220 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f  C_MEM       3  /
37230 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
37240 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
37250 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
37260 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f  C_MEM2      4  /
37270 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23 64  * NOT USED */.#d
37280 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
37290 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20 20  EX_STATIC_OPEN  
372a0 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
372b0 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f 0a  3BtreeOpen() */.
372c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
372d0 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
372e0 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69        5  /* sqli
372f0 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a  te3_random() */.
37300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
37310 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20  UTEX_STATIC_LRU 
37320 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20        6  /* lru 
37330 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65  page list */.#de
37340 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
37350 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20  X_STATIC_LRU2   
37360 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67     7  /* lru pag
37370 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  e list */../*.**
37380 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
37390 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f  eve the mutex fo
373a0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
373b0 6e 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d  nection {H17002}
373c0 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H17000>.**.** 
373d0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  This interface r
373e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
373f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
37400 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  tex] object that
37410 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20   .** serializes 
37420 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64  access to the [d
37430 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37440 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65  on] given in the
37450 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65   argument.** whe
37460 6e 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  n the [threading
37470 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c   mode] is Serial
37480 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ized..** If the 
37490 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
374a0 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   is Single-threa
374b0 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61  d or Multi-threa
374c0 64 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72  d then this.** r
374d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
374e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
374f0 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  /.sqlite3_mutex 
37500 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  *sqlite3_db_mute
37510 78 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  x(sqlite3*);../*
37520 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
37530 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20  w-Level Control 
37540 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  Of Database File
37550 73 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38  s {H11300} <S308
37560 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30  00>.**.** {H1130
37570 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
37580 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
37590 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
375a0 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f  a direct call to
375b0 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e   the.** xFileCon
375c0 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20  trol method for 
375d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
375e0 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
375f0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
37600 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
37610 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66  database identif
37620 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
37630 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31  d argument. {H11
37640 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65  302} The.** name
37650 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
37660 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73   is the name ass
37670 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74  igned to the dat
37680 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20  abase by the.** 
37690 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74  <a href="lang_at
376a0 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43  tach.html">ATTAC
376b0 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e  H</a> SQL comman
376c0 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68  d that opened th
376d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b  e.** database. {
376e0 48 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72  H11303} To contr
376f0 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  ol the main data
37700 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74  base file, use t
37710 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a  he name "main".*
37720 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * or a NULL poin
37730 74 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68  ter. {H11304} Th
37740 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
37750 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
37760 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
37770 20 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65   are passed dire
37780 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20  ctly through to 
37790 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
377a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20  hird parameters 
377b0 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43  of.** the xFileC
377c0 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20  ontrol method.  
377d0 7b 48 31 31 33 30 35 7d 20 54 68 65 20 72 65 74  {H11305} The ret
377e0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
377f0 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a   xFileControl.**
37800 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20   method becomes 
37810 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
37820 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
37830 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d  ..**.** {H11306}
37840 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70   If the second p
37850 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d  arameter (zDbNam
37860 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  e) does not matc
37870 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e  h the name of an
37880 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61  y.** open databa
37890 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51  se file, then SQ
378a0 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65  LITE_ERROR is re
378b0 74 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d  turned. {H11307}
378c0 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63   This error.** c
378d0 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d  ode is not remem
378e0 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e  bered and will n
378f0 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62  ot be recalled b
37900 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  y [sqlite3_errco
37910 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  de()].** or [sql
37920 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20  ite3_errmsg()]. 
37930 7b 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64  {A11308} The und
37940 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e  erlying xFileCon
37950 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68  trol method migh
37960 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e  t.** also return
37970 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
37980 7b 41 31 31 33 30 39 7d 20 54 68 65 72 65 20 69  {A11309} There i
37990 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74  s no way to dist
379a0 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a  inguish between.
379b0 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20  ** an incorrect 
379c0 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53  zDbName and an S
379d0 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75  QLITE_ERROR retu
379e0 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65  rn from the unde
379f0 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43  rlying.** xFileC
37a00 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b  ontrol method. {
37a10 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  END}.**.** See a
37a20 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  lso: [SQLITE_FCN
37a30 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f  TL_LOCKSTATE].*/
37a40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  .int sqlite3_fil
37a50 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65  e_control(sqlite
37a60 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
37a70 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c  zDbName, int op,
37a80 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
37a90 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e  CAPI3REF: Testin
37aa0 67 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31  g Interface {H11
37ab0 34 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a  400} <S30800>.**
37ac0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
37ad0 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69  test_control() i
37ae0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
37af0 20 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74   to read out int
37b00 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f  ernal.** state o
37b10 66 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20  f SQLite and to 
37b20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e  inject faults in
37b30 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65  to SQLite for te
37b40 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65  sting.** purpose
37b50 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
37b60 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70  rameter is an op
37b70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61  eration code tha
37b80 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
37b90 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e  the number, mean
37ba0 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69  ing, and operati
37bb0 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71  on of all subseq
37bc0 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e  uent parameters.
37bd0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
37be0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72  rface is not for
37bf0 20 75 73 65 20 62 79 20 61 70 70 6c 69 63 61 74   use by applicat
37c00 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73  ions.  It exists
37c10 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76   solely.** for v
37c20 65 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72  erifying the cor
37c30 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f  rect operation o
37c40 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
37c50 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67  rary.  Depending
37c60 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53  .** on how the S
37c70 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 73  QLite library is
37c80 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20   compiled, this 
37c90 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
37ca0 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a  not exist..**.**
37cb0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
37cc0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f  the operation co
37cd0 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69  des, their meani
37ce0 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74  ngs, the paramet
37cf0 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65  ers.** they take
37d00 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65 79 20  , and what they 
37d10 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65  do are all subje
37d20 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
37d30 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20  hout notice..** 
37d40 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74  Unlike most of t
37d50 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74  he SQLite API, t
37d60 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
37d70 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
37d80 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e  o.** operate con
37d90 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f  sistently from o
37da0 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
37db0 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73  e next..*/.int s
37dc0 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74  qlite3_test_cont
37dd0 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  rol(int op, ...)
37de0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37df0 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72  F: Testing Inter
37e00 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43  face Operation C
37e10 6f 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48  odes {H11410} <H
37e20 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  11400>.**.** The
37e30 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
37e40 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61   the valid opera
37e50 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65  tion code parame
37e60 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20  ters used.** as 
37e70 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
37e80 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
37e90 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a  est_control()]..
37ea0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61  **.** These para
37eb0 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65 69 72  meters and their
37ec0 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75   meanings are su
37ed0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a  bject to change.
37ee0 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63  ** without notic
37ef0 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65 73  e.  These values
37f00 20 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67   are for testing
37f10 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a   purposes only..
37f20 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
37f30 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61  should not use a
37f40 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  ny of these para
37f50 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a  meters or the.**
37f60 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63   [sqlite3_test_c
37f70 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
37f80 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
37f90 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
37fa0 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20  PRNG_SAVE       
37fb0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
37fc0 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
37fd0 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20  RL_PRNG_RESTORE 
37fe0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
37ff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53  efine SQLITE_TES
38000 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54  TCTRL_PRNG_RESET
38010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
38020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38030 54 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f  TESTCTRL_BITVEC_
38040 54 45 53 54 20 20 20 20 20 20 20 20 20 20 20 20  TEST            
38050 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
38060 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c  TE_TESTCTRL_FAUL
38070 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20  T_INSTALL       
38080 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
38090 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42  QLITE_TESTCTRL_B
380a0 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f  ENIGN_MALLOC_HOO
380b0 4b 53 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e  KS     10.#defin
380c0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
380d0 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45 20 20  L_PENDING_BYTE  
380e0 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
380f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
38100 43 54 52 4c 5f 41 53 53 45 52 54 20 20 20 20 20  CTRL_ASSERT     
38110 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
38120 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
38130 45 53 54 43 54 52 4c 5f 41 4c 57 41 59 53 20 20  ESTCTRL_ALWAYS  
38140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38150 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
38160 45 5f 54 45 53 54 43 54 52 4c 5f 52 45 53 45 52  E_TESTCTRL_RESER
38170 56 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  VE              
38180 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     14../*.** CAP
38190 49 33 52 45 46 3a 20 53 51 4c 69 74 65 20 52 75  I3REF: SQLite Ru
381a0 6e 74 69 6d 65 20 53 74 61 74 75 73 20 7b 48 31  ntime Status {H1
381b0 37 32 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a  7200} <S60200>.*
381c0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
381d0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
381e0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ace is used to r
381f0 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65 20  etrieve runtime 
38200 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74 69  status informati
38210 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  on.** about the 
38220 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f 66 20 53  preformance of S
38230 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70 74 69 6f  QLite, and optio
38240 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65 74 20 76  nally to reset v
38250 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67 68 77 61  arious.** highwa
38260 74 65 72 20 6d 61 72 6b 73 2e 20 20 54 68 65 20  ter marks.  The 
38270 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
38280 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
38290 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 70 65  e for.** the spe
382a0 63 69 66 69 63 20 70 61 72 61 6d 65 74 65 72 20  cific parameter 
382b0 74 6f 20 6d 65 61 73 75 72 65 2e 20 20 52 65 63  to measure.  Rec
382c0 6f 67 6e 69 7a 65 64 20 69 6e 74 65 67 65 72 20  ognized integer 
382d0 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20 6f 66 20  codes.** are of 
382e0 74 68 65 20 66 6f 72 6d 20 5b 53 51 4c 49 54 45  the form [SQLITE
382f0 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59 5f 55  _STATUS_MEMORY_U
38300 53 45 44 20 7c 20 53 51 4c 49 54 45 5f 53 54 41  SED | SQLITE_STA
38310 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a 20 54 68 65  TUS_...]..** The
38320 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
38330 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
38340 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e 74 6f  is returned into
38350 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a 2a 20 54   *pCurrent..** T
38360 68 65 20 68 69 67 68 65 73 74 20 72 65 63 6f 72  he highest recor
38370 64 65 64 20 76 61 6c 75 65 20 69 73 20 72 65 74  ded value is ret
38380 75 72 6e 65 64 20 69 6e 20 2a 70 48 69 67 68 77  urned in *pHighw
38390 61 74 65 72 2e 20 20 49 66 20 74 68 65 0a 2a 2a  ater.  If the.**
383a0 20 72 65 73 65 74 46 6c 61 67 20 69 73 20 74 72   resetFlag is tr
383b0 75 65 2c 20 74 68 65 6e 20 74 68 65 20 68 69 67  ue, then the hig
383c0 68 65 73 74 20 72 65 63 6f 72 64 20 76 61 6c 75  hest record valu
383d0 65 20 69 73 20 72 65 73 65 74 20 61 66 74 65 72  e is reset after
383e0 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20  .** *pHighwater 
383f0 69 73 20 77 72 69 74 74 65 6e 2e 20 53 6f 6d 65  is written. Some
38400 20 70 61 72 61 6d 65 74 65 72 73 20 64 6f 20 6e   parameters do n
38410 6f 74 20 72 65 63 6f 72 64 20 74 68 65 20 68 69  ot record the hi
38420 67 68 65 73 74 0a 2a 2a 20 76 61 6c 75 65 2e 20  ghest.** value. 
38430 20 46 6f 72 20 74 68 6f 73 65 20 70 61 72 61 6d   For those param
38440 65 74 65 72 73 0a 2a 2a 20 6e 6f 74 68 69 6e 67  eters.** nothing
38450 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
38460 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 6e 64   *pHighwater and
38470 20 74 68 65 20 72 65 73 65 74 46 6c 61 67 20 69   the resetFlag i
38480 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 4f 74  s ignored..** Ot
38490 68 65 72 20 70 61 72 61 6d 65 74 65 72 73 20 72  her parameters r
384a0 65 63 6f 72 64 20 6f 6e 6c 79 20 74 68 65 20 68  ecord only the h
384b0 69 67 68 77 61 74 65 72 20 6d 61 72 6b 20 61 6e  ighwater mark an
384c0 64 20 6e 6f 74 20 74 68 65 20 63 75 72 72 65 6e  d not the curren
384d0 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72  t.** value.  For
384e0 20 74 68 65 73 65 20 6c 61 74 74 65 72 20 70 61   these latter pa
384f0 72 61 6d 65 74 65 72 73 20 6e 6f 74 68 69 6e 67  rameters nothing
38500 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
38510 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a 2a 0a 2a   *pCurrent..**.*
38520 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
38530 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
38540 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
38550 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 5b 65  a non-zero.** [e
38560 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61  rror code] on fa
38570 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ilure..**.** Thi
38580 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 72  s routine is thr
38590 65 61 64 73 61 66 65 20 62 75 74 20 69 73 20 6e  eadsafe but is n
385a0 6f 74 20 61 74 6f 6d 69 63 2e 20 20 54 68 69 73  ot atomic.  This
385b0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 0a   routine can be.
385c0 2a 2a 20 63 61 6c 6c 65 64 20 77 68 69 6c 65 20  ** called while 
385d0 6f 74 68 65 72 20 74 68 72 65 61 64 73 20 61 72  other threads ar
385e0 65 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 73 61  e running the sa
385f0 6d 65 20 6f 72 20 64 69 66 66 65 72 65 6e 74 20  me or different 
38600 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66  SQLite.** interf
38610 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 20 74  aces.  However t
38620 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
38630 65 64 20 69 6e 20 2a 70 43 75 72 72 65 6e 74 20  ed in *pCurrent 
38640 61 6e 64 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74  and.** *pHighwat
38650 65 72 20 72 65 66 6c 65 63 74 20 74 68 65 20 73  er reflect the s
38660 74 61 74 75 73 20 6f 66 20 53 51 4c 69 74 65 20  tatus of SQLite 
38670 61 74 20 64 69 66 66 65 72 65 6e 74 20 70 6f 69  at different poi
38680 6e 74 73 20 69 6e 20 74 69 6d 65 0a 2a 2a 20 61  nts in time.** a
38690 6e 64 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  nd it is possibl
386a0 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
386b0 68 72 65 61 64 20 6d 69 67 68 74 20 63 68 61 6e  hread might chan
386c0 67 65 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ge the parameter
386d0 0a 2a 2a 20 69 6e 20 62 65 74 77 65 65 6e 20 74  .** in between t
386e0 68 65 20 74 69 6d 65 73 20 77 68 65 6e 20 2a 70  he times when *p
386f0 43 75 72 72 65 6e 74 20 61 6e 64 20 2a 70 48 69  Current and *pHi
38700 67 68 77 61 74 65 72 20 61 72 65 20 77 72 69 74  ghwater are writ
38710 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ten..**.** See a
38720 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62  lso: [sqlite3_db
38730 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2f 0a 53 51  _status()].*/.SQ
38740 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
38750 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  L int sqlite3_st
38760 61 74 75 73 28 69 6e 74 20 6f 70 2c 20 69 6e 74  atus(int op, int
38770 20 2a 70 43 75 72 72 65 6e 74 2c 20 69 6e 74 20   *pCurrent, int 
38780 2a 70 48 69 67 68 77 61 74 65 72 2c 20 69 6e 74  *pHighwater, int
38790 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 0a 2f   resetFlag);.../
387a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
387b0 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73  tatus Parameters
387c0 20 7b 48 31 37 32 35 30 7d 20 3c 48 31 37 32 30   {H17250} <H1720
387d0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
387e0 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  AL.**.** These i
387f0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
38800 20 64 65 73 69 67 6e 61 74 65 20 76 61 72 69 6f   designate vario
38810 75 73 20 72 75 6e 2d 74 69 6d 65 20 73 74 61 74  us run-time stat
38820 75 73 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  us parameters.**
38830 20 74 68 61 74 20 63 61 6e 20 62 65 20 72 65 74   that can be ret
38840 75 72 6e 65 64 20 62 79 20 5b 73