/ Hex Artifact Content
Login

Artifact 338e1ac00faa7e3a536e7f1120827dd1f6432981:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  rsion.**.** Thes
10b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f  e interfaces pro
10c0: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
10d0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
10e0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
10f0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ],.** [SQLITE_VE
1100: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61  RSION_NUMBER], a
1110: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  nd [SQLITE_SOURC
1120: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1130: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62  ssor macros.** b
1140: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  ut are associate
1150: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
1160: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
1170: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
1180: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
1190: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
11a0: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
11b0: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
11c0: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
11d0: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
11e0: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
11f0: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
1200: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
1210: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
1220: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
1230: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
1240: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
1250: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
1260: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
1270: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
1280: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
1290: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
12a0: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
12b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
12c0: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
12d0: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
12e0: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
12f0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1300: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
1310: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
1320: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
1330: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1340: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
1350: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
1360: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1370: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1380: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1390: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
13a0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
13b0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
13c0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
13d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
13e0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
13f0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1400: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1410: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1420: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1430: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1450: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1460: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
1470: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1480: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1490: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
14a0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
14b0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
14c0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
14d0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
14e0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
14f0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1500: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1510: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1520: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1530: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
1540: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
1550: 75 6e 63 74 69 6f 6e 20 61 20 70 6f 69 6e 74 65  unction a pointe
1560: 72 0a 2a 2a 20 74 6f 20 61 20 73 74 72 69 6e 67  r.** to a string
1570: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
1580: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
1590: 65 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  e as the [SQLITE
15a0: 5f 53 4f 55 52 43 45 5f 49 44 5d 0a 2a 2a 20 43  _SOURCE_ID].** C
15b0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15c0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15d0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
15e0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
15f0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1600: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1610: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1620: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1630: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1640: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1650: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1660: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1670: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1680: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1690: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16b0: 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
16c0: 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54  The Library Is T
16d0: 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31 30  hreadsafe {H1010
16e0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
16f0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1700: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1710: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1720: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1730: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1740: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1750: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1760: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1770: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1780: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1790: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
17a0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
17b0: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
17c0: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
17d0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
17e0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
17f0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1800: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1810: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1820: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1830: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1840: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1850: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1860: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1870: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1880: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1890: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
18a0: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
18b0: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
18c0: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
18d0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
18e0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
18f0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1900: 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
1910: 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72   behavior is for
1920: 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65   mutexes to be e
1930: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  nabled..**.** Th
1940: 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
1950: 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61   be used by an a
1960: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61  pplication to ma
1970: 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65  ke sure that the
1980: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  .** version of S
1990: 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73  QLite that it is
19a0: 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74   linking against
19b0: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
19c0: 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65  th.** the desire
19d0: 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65  d setting of the
19e0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
19f0: 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  AFE] macro..**.*
1a00: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1a10: 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e   only reports on
1a20: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
1a30: 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a  e mutex setting.
1a40: 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ** of the [SQLIT
1a50: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c  E_THREADSAFE] fl
1a60: 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ag.  If SQLite i
1a70: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1a80: 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  ** SQLITE_THREAD
1a90: 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74 65  SAFE=1 then mute
1aa0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
1ab0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
1ac0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
1ad0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
1ae0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
1af0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
1b00: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
1b10: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
1b20: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
1b30: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
1b40: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
1b50: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
1b60: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
1b70: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
1b80: 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e 63  lue of this func
1b90: 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f 6e  tion shows.** on
1ba0: 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20 63  ly the default c
1bb0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74  ompile-time sett
1bc0: 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e  ing, not any run
1bd0: 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a 2a  -time changes.**
1be0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
1bf0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20  ..**.** See the 
1c00: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1c10: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
1c20: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
1c30: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1c40: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
1c50: 48 31 30 31 30 31 5d 20 5b 48 31 30 31 30 32 5d  H10101] [H10102]
1c60: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1c70: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
1c80: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c90: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
1ca0: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 48  ection Handle {H
1cb0: 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a  12000} <S40200>.
1cc0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
1cd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ce0: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
1cf0: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
1d00: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
1d10: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
1d20: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
1d30: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
1d40: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
1d50: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
1d60: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
1d70: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
1d80: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
1d90: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
1da0: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
1db0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
1dc0: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1dd0: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
1de0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1df0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
1e00: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
1e10: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
1e20: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69  e3_close()].** i
1e30: 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  s its destructor
1e40: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e  .  There are man
1e50: 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63  y other interfac
1e60: 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b  es (such as.** [
1e70: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e80: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
1e90: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
1ea0: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1eb0: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1ec0: 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20  ()] to name but 
1ed0: 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20  three) that are 
1ee0: 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a  methods on an.**
1ef0: 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e   sqlite3 object.
1f00: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1f10: 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74  ct sqlite3 sqlit
1f20: 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e3;../*.** CAPI3
1f30: 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65  REF: 64-Bit Inte
1f40: 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32 30  ger Types {H1020
1f50: 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20 4b  0} <S10110>.** K
1f60: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
1f70: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
1f80: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
1f90: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
1fa0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
1fb0: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
1fc0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
1fd0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
1fe0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
1ff0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
2000: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2010: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2020: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2030: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2040: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
2050: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
2060: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
2070: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
2080: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
2090: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
20a0: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
20b0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
20c0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ly..**.** Requir
20d0: 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31 5d  ements: [H10201]
20e0: 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69 66   [H10202].*/.#if
20f0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2100: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
2110: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2120: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2130: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2140: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2150: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2160: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2170: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2180: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2190: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
21a0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
21b0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
21c0: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
21d0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
21e0: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
21f0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2200: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2210: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2220: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2230: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2240: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2250: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2260: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2270: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2280: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2290: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
22a0: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
22b0: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
22c0: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
22d0: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
22e0: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
22f0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2300: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2310: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2320: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2330: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2340: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2350: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2360: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2370: 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c  ction {H12010} <
2380: 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a  S30100><S40200>.
2390: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
23a0: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
23b0: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
23c0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
23d0: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
23e0: 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 33 5f  s must [sqlite3_
23f0: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2400: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
2410: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a  ed statements].*
2420: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
2430: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
2440: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
2450: 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64  dles] associated
2460: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71   with.** the [sq
2470: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2480: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2490: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
24a0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
24b0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
24c0: 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69  ] is invoked whi
24d0: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
24e0: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
24f0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2500: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
2510: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
2520: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72   The C parameter
2530: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
2540: 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65  se(C)] must be e
2550: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  ither a NULL.** 
2560: 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73  pointer or an [s
2570: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
2580: 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a  ointer obtained.
2590: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
25a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
25b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
25c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
25d0: 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74  n_v2()], and not
25e0: 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73   previously clos
25f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ed..**.** Requir
2600: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 30  ements:.** [H120
2610: 31 31 5d 20 5b 48 31 32 30 31 32 5d 20 5b 48 31  11] [H12012] [H1
2620: 32 30 31 33 5d 20 5b 48 31 32 30 31 34 5d 20 5b  2013] [H12014] [
2630: 48 31 32 30 31 35 5d 20 5b 48 31 32 30 31 39 5d  H12015] [H12019]
2640: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2650: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29  close(sqlite3 *)
2660: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
2670: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
2680: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
2690: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
26a0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
26b0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
26c0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
26d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
26e0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
26f0: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
2700: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
2710: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
2720: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
2730: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2740: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
2750: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
2760: 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c  rface {H12100} <
2770: 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10000>.**.** Th
2780: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2790: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
27a0: 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f  convenient way o
27b0: 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72  f running one or
27c0: 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61   more.** SQL sta
27d0: 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20  tements without 
27e0: 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20  having to write 
27f0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
2800: 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f    The UTF-8 enco
2810: 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ded.** SQL state
2820: 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73 65 64  ments are passed
2830: 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e   in as the secon
2840: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2850: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a  qlite3_exec()..*
2860: 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73  * The statements
2870: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f   are evaluated o
2880: 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20  ne by one until 
2890: 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20  either an error 
28a0: 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75  or.** an interru
28b0: 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65  pt is encountere
28c0: 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79  d, or until they
28d0: 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20   are all done.  
28e0: 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
28f0: 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f  r.** is an optio
2900: 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61  nal callback tha
2910: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  t is invoked onc
2920: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  e for each row o
2930: 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72  f any query.** r
2940: 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20  esults produced 
2950: 62 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  by the SQL state
2960: 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20  ments.  The 5th 
2970: 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20  parameter tells 
2980: 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74  where.** to writ
2990: 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  e any error mess
29a0: 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ages..**.** The 
29b0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61  error message pa
29c0: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67  ssed back throug
29d0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
29e0: 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69  ter is held.** i
29f0: 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
2a00: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2a10: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61  malloc()].  To a
2a20: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
2a30: 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69  ak,.** the calli
2a40: 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  ng application s
2a50: 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69  hould call [sqli
2a60: 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61  te3_free()] on a
2a70: 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  ny error.** mess
2a80: 61 67 65 20 72 65 74 75 72 6e 65 64 20 74 68 72  age returned thr
2a90: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
2aa0: 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20 68  ameter when it h
2ab0: 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
2ac0: 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  g.** the error m
2ad0: 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  essage..**.** If
2ae0: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2af0: 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61  nt in the 2nd pa
2b00: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
2b10: 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  or an empty stri
2b20: 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e  ng.** or a strin
2b30: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c  g containing onl
2b40: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
2b50: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
2b60: 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  no SQL.** statem
2b70: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
2b80: 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  ed and the datab
2b90: 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  ase is not chang
2ba0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
2bb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
2bc0: 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
2bd0: 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f  ented in terms o
2be0: 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  f.** [sqlite3_pr
2bf0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2c00: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
2c10: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
2c20: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lize()]..** The 
2c30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72  sqlite3_exec() r
2c40: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68  outine does noth
2c50: 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62  ing to the datab
2c60: 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ase that cannot 
2c70: 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73  be done.** by [s
2c80: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c90: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
2ca0: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
2cb0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2cc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2cd0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
2ce0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
2cf0: 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64  must be an valid
2d00: 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 5b 64 61   and open.** [da
2d10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d20: 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 61  n]..**.** The da
2d30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d40: 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 6c  n must not be cl
2d50: 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 5b 73  osed while.** [s
2d60: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
2d70: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2d80: 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
2d90: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
2da0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2db0: 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 74 68 65  ] to free.** the
2dc0: 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72   memory that *er
2dd0: 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69  rmsg is left poi
2de0: 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68  nting at once th
2df0: 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
2e00: 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ge is no longer 
2e10: 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  needed..**.** Th
2e20: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2e30: 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20  text in the 2nd 
2e40: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2e50: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a  lite3_exec()].**
2e60: 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63   must remain unc
2e70: 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71  hanged while [sq
2e80: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
2e90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
2ea0: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
2eb0: 20 5b 48 31 32 31 30 31 5d 20 5b 48 31 32 31 30   [H12101] [H1210
2ec0: 32 5d 20 5b 48 31 32 31 30 34 5d 20 5b 48 31 32  2] [H12104] [H12
2ed0: 31 30 35 5d 20 5b 48 31 32 31 30 37 5d 20 5b 48  105] [H12107] [H
2ee0: 31 32 31 31 30 5d 20 5b 48 31 32 31 31 33 5d 20  12110] [H12113] 
2ef0: 5b 48 31 32 31 31 36 5d 0a 2a 2a 20 5b 48 31 32  [H12116].** [H12
2f00: 31 31 39 5d 20 5b 48 31 32 31 32 32 5d 20 5b 48  119] [H12122] [H
2f10: 31 32 31 32 35 5d 20 5b 48 31 32 31 33 31 5d 20  12125] [H12131] 
2f20: 5b 48 31 32 31 33 34 5d 20 5b 48 31 32 31 33 37  [H12134] [H12137
2f30: 5d 20 5b 48 31 32 31 33 38 5d 0a 2a 2f 0a 69 6e  ] [H12138].*/.in
2f40: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
2f50: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
2f60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f70: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2f80: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
2f90: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2fa0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
2fb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fc0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
2fd0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
2fe0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
2ff0: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3000: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3010: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3020: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3040: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3050: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3060: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3070: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3080: 20 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 2f 2a 20 45 72 72 6f           /* Erro
30a0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
30b0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
30c0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
30d0: 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d 20   Codes {H10210} 
30e0: 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S10700>.** KEYW
30f0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3100: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3110: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
3120: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
3130: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
3140: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
3150: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
3160: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
3170: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
3180: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
3190: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
31a0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20  er to indicates 
31b0: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
31c0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
31d0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
31e0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
31f0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
3200: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
3210: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
3220: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
3230: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
3240: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
3250: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
3260: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
3270: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
3280: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
3290: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
32a0: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
32b0: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
32c0: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
32d0: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
32e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
32f0: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
3300: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  * Internal logic
3310: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
3320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3330: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
3340: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
3350: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
3360: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3370: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
3380: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
3390: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
33a0: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
33b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
33c0: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
33d0: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
33e0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
33f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
3400: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
3410: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
3420: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
3430: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
3440: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
3450: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
3460: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
3470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
3480: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
3490: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
34a0: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
34b0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
34c0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
34d0: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
34e0: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
34f0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
3500: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
3510: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
3520: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
3530: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
3540: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
3550: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3560: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
3570: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
3580: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
3590: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
35a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35b0: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
35c0: 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61   /* NOT USED. Ta
35d0: 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f  ble or record no
35e0: 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69  t found */.#defi
35f0: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
3600: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
3610: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
3620: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
3630: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
3640: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
3650: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
3660: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
3670: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
3680: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3690: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
36a0: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44    /* NOT USED. D
36b0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
36c0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
36d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
36e0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
36f0: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
3700: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
3710: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
3720: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
3730: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
3740: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
3750: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
3760: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
3770: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
3780: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
3790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37a0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
37b0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
37c0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
37d0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
37e0: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
37f0: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
3800: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
3810: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3820: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
3830: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
3840: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
3850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3860: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
3870: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
3880: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
3890: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
38a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
38b0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
38c0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
38d0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
38e0: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
38f0: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
3900: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
3910: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
3920: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
3930: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
3940: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
3950: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
3960: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
3970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
3980: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
3990: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
39a0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
39b0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
39c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
39d0: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
39e0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
39f0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
3a00: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
3a10: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
3a20: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
3a30: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
3a40: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
3a50: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
3a60: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
3a70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
3a80: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
3a90: 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c 53  odes {H10220} <S
3aa0: 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10700>.** KEYWOR
3ab0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72  DS: {extended er
3ac0: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ror code} {exten
3ad0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d  ded error codes}
3ae0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
3af0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3b00: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72  ode} {extended r
3b10: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
3b20: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
3b30: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
3b40: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
3b50: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
3b60: 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a  of 26 integer.**
3b70: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
3b80: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
3b90: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
3ba0: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
3bb0: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
3bc0: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
3bd0: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
3be0: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
3bf0: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
3c00: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
3c10: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
3c20: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
3c30: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
3c40: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
3c50: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
3c60: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
3c70: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
3c80: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
3c90: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
3ca0: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
3cb0: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
3cc0: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
3cd0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
3ce0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
3cf0: 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74   errors. The ext
3d00: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
3d10: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f  es are enabled o
3d20: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e  r disabled.** on
3d30: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20   a per database 
3d40: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
3d50: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
3d60: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
3d70: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20  result_codes()] 
3d80: 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  API..**.** Some 
3d90: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  of the available
3da0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
3db0: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65   codes are liste
3dc0: 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d  d here..** One m
3dd0: 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75  ay expect the nu
3de0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64  mber of extended
3df0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69   result codes wi
3e00: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20  ll be expand.** 
3e10: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74  over time.  Soft
3e20: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65  ware that uses e
3e30: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3e40: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65  odes should expe
3e50: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77  ct.** to see new
3e60: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e   result codes in
3e70: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
3e80: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
3e90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
3ea0: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
3eb0: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
3ec0: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
3ed0: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
3ee0: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69  y zero..*/.#defi
3ef0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
3f00: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
3f10: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
3f20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
3f30: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
3f40: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
3f50: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3f60: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
3f70: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
3f80: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
3f90: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3fa0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
3fb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
3fc0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
3fd0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3fe0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
3ff0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
4000: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
4010: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
4020: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4030: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
4040: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
4050: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
4060: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4070: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
4080: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4090: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
40a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
40b0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
40c0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
40d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
40e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
40f0: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
4100: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4110: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
4120: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4130: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
4140: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4150: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
4160: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4170: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
4180: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4190: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
41a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
41b0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
41c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
41d0: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
41e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
41f0: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
4200: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4210: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
4220: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4230: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
4240: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
4250: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
4260: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4270: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
4280: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4290: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
42a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
42b0: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
42c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
42d0: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
42e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
42f0: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
4300: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4310: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
4320: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4330: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
4340: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
4350: 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c 38 29  _LOCKED | (1<<8)
4360: 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   )../*.** CAPI3R
4370: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
4380: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
4390: 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31  ns {H10230} <H11
43a0: 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a  120> <H12700>.**
43b0: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
43c0: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
43d0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
43e0: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
43f0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
4400: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
4410: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
4420: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
4430: 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  er to the xOpen 
4440: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a  method of the.**
4450: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
4460: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
4470: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
4480: 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30  ADONLY         0
4490: 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b  x00000001  /* Ok
44a0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
44b0: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
44c0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
44d0: 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30  ADWRITE        0
44e0: 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b  x00000002  /* Ok
44f0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
4500: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
4510: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  e SQLITE_OPEN_CR
4520: 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30  EATE           0
4530: 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b  x00000004  /* Ok
4540: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
4550: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
4560: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45  e SQLITE_OPEN_DE
4570: 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30  LETEONCLOSE    0
4580: 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46  x00000008  /* VF
4590: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
45a0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
45b0: 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30  CLUSIVE        0
45c0: 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46  x00000010  /* VF
45d0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
45e0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
45f0: 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  IN_DB          0
4600: 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46  x00000100  /* VF
4610: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
4620: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
4630: 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  MP_DB          0
4640: 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46  x00000200  /* VF
4650: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
4660: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52  e SQLITE_OPEN_TR
4670: 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30  ANSIENT_DB     0
4680: 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46  x00000400  /* VF
4690: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
46a0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
46b0: 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  IN_JOURNAL     0
46c0: 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46  x00000800  /* VF
46d0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
46f0: 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  MP_JOURNAL     0
4700: 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46  x00001000  /* VF
4710: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
4720: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55  e SQLITE_OPEN_SU
4730: 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30  BJOURNAL       0
4740: 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46  x00002000  /* VF
4750: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
4760: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
4770: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30  STER_JOURNAL   0
4780: 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46  x00004000  /* VF
4790: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f  e SQLITE_OPEN_NO
47b0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30  MUTEX          0
47c0: 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b  x00008000  /* Ok
47d0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
47e0: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
47f0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55  e SQLITE_OPEN_FU
4800: 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30  LLMUTEX        0
4810: 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b  x00010000  /* Ok
4820: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
4830: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
4840: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  e SQLITE_OPEN_SH
4850: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30  AREDCACHE      0
4860: 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b  x00020000  /* Ok
4870: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
4880: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
4890: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
48a0: 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30  IVATECACHE     0
48b0: 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b  x00040000  /* Ok
48c0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
48d0: 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n_v2() */../*.**
48e0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
48f0: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
4900: 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31  s {H10240} <H111
4910: 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  20>.**.** The xD
4920: 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65  eviceCapabilitie
4930: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
4940: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
4950: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
4960: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
4970: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
4980: 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65  tor of the these
4990: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
49a0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
49b0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
49c0: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
49d0: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
49e0: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
49f0: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
4a00: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
4a10: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
4a20: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
4a30: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
4a40: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
4a50: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
4a60: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
4a70: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
4a80: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
4a90: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
4aa0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
4ab0: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
4ac0: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
4ad0: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
4ae0: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
4af0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
4b00: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
4b10: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
4b20: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
4b30: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
4b40: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
4b50: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
4b60: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
4b70: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
4b80: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
4b90: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
4ba0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
4bb0: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
4bc0: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
4bd0: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
4be0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
4bf0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
4c00: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
4c10: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
4c20: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
4c30: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
4c40: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
4c50: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66  Write()..*/.#def
4c60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4c70: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
4c80: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
4c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4ca0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
4cb0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
4cc0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4cd0: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
4ce0: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
4cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4d00: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
4d10: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
4d20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4d30: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
4d40: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
4d50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4d60: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
4d70: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
4d80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4d90: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
4da0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
4db0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4dc0: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
4dd0: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
4de0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4df0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
4e00: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
4e10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4e20: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
4e30: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
4e40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
4e50: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
4e60: 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a   0x00000400../*.
4e70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
4e80: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
4e90: 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32   {H10250} <H1112
4ea0: 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a  0> <H11310>.**.*
4eb0: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
4ec0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
4ed0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
4ee0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
4ef0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
4f00: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
4f10: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
4f20: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
4f30: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
4f40: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
4f50: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4f60: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
4f70: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
4f80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
4f90: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
4fa0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
4fb0: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
4fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4fd0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
4fe0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
4ff0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
5000: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
5010: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
5020: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
5030: 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31  ags {H10260} <H1
5040: 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  1120>.**.** When
5050: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
5060: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
5070: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
5080: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5090: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
50a0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
50b0: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
50c0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
50d0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
50e0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
50f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
5100: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
5110: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
5120: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
5130: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
5140: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
5150: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
5160: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
5170: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
5180: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
5190: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
51a0: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
51b0: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
51c0: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
51d0: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
51e0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
51f0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
5200: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
5210: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
5220: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
5230: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
5240: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
5250: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
5260: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64  f fsync()..*/.#d
5270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
5280: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
5290: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
52a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
52b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
52c0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
52d0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
52e0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
52f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
5300: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
5310: 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 31  ile Handle {H111
5320: 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  10} <S20110>.**.
5330: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5340: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5350: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5360: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5370: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5380: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5390: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
53a0: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
53b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
53c0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
53d0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
53e0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
53f0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5400: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5410: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5420: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5430: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
5440: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
5450: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
5460: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
5470: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
5480: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
5490: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
54a0: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
54b0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
54c0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
54d0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
54e0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
54f0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
5500: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
5510: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
5520: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
5530: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
5540: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
5550: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
5560: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
5570: 65 63 74 20 7b 48 31 31 31 32 30 7d 20 3c 53 32  ect {H11120} <S2
5580: 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72  0110>.**.** Ever
5590: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
55a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
55b0: 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  s] xOpen method 
55c0: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
55d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
55e0: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
55f0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
5600: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
5610: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
5620: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
5630: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
5640: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
5650: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
5660: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
5670: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
5680: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
5690: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
56a0: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
56b0: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
56c0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
56d0: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
56e0: 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20  ** If the xOpen 
56f0: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
5700: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
5710: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
5720: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
5730: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
5740: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
5750: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
5760: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
5770: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
5780: 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20   xOpen reported 
5790: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
57a0: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
57b0: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
57c0: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
57d0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
57e0: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20  xOpen.** is for 
57f0: 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74  the xOpen to set
5800: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
5810: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
5820: 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  nt to NULL..**.*
5830: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
5840: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
5850: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
5860: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
5870: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
5880: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
5890: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
58a0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
58b0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
58c0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
58d0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
58e0: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
58f0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
5900: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
5910: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
5920: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
5930: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
5940: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
5950: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
5960: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
5970: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
5980: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
5990: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
59a0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
59b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
59c0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
59d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
59e0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
59f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5a00: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
5a10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5a20: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
5a30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5a40: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
5a50: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
5a60: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
5a70: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
5a80: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
5a90: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
5aa0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
5ab0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
5ac0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
5ad0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
5ae0: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
5af0: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
5b00: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
5b10: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
5b20: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
5b30: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
5b40: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
5b50: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
5b60: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
5b70: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
5b80: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
5b90: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
5ba0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
5bb0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
5bc0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
5bd0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
5be0: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
5bf0: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
5c00: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
5c10: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
5c20: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
5c30: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
5c40: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
5c50: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
5c60: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
5c70: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
5c80: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
5c90: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
5ca0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
5cb0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
5cc0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
5cd0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
5ce0: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
5cf0: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
5d00: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
5d10: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
5d20: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
5d30: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
5d40: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
5d50: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
5d60: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
5d70: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
5d80: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
5d90: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
5da0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
5db0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
5dc0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
5dd0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
5de0: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
5df0: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
5e00: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
5e10: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
5e20: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
5e30: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
5e40: 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45  se..** A [SQLITE
5e50: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
5e60: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
5e70: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
5e80: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
5e90: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
5ea0: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
5eb0: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
5ec0: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
5ed0: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
5ee0: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
5ef0: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
5f00: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ts..**.** The xS
5f10: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
5f20: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
5f30: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
5f40: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
5f50: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
5f60: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
5f70: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
5f80: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
5f90: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
5fa0: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
5fb0: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
5fc0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
5fd0: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
5fe0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
5ff0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
6000: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
6010: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
6020: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
6030: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
6040: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
6050: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6060: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
6070: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6080: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
6090: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
60a0: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
60b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
60c0: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
60d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
60e0: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
60f0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6100: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
6110: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6120: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
6130: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6140: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
6150: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6160: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
6170: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6180: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6190: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
61a0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
61b0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
61c0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
61d0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
61e0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
61f0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
6200: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
6210: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
6220: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
6230: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
6240: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
6250: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
6260: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
6270: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
6280: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
6290: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
62a0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
62b0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
62c0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
62d0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
62e0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
62f0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
6300: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
6310: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
6320: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
6330: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
6340: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
6350: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
6360: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
6370: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
6380: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6390: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
63a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
63b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
63c0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
63d0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
63e0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
63f0: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
6400: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
6410: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
6420: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
6430: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
6440: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
6450: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
6460: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
6470: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
6480: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
6490: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
64a0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
64b0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
64c0: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
64d0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
64e0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
64f0: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
6500: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
6510: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
6520: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
6530: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
6540: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
6550: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6560: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
6570: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
6580: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
6590: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
65a0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
65b0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
65c0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
65d0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
65e0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
65f0: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
6600: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
6610: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
6620: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
6630: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
6640: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
6650: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
6660: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
6670: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
6680: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
6690: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
66a0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
66b0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
66c0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
66d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
66e0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
66f0: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
6700: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
6710: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
6720: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
6730: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
6740: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
6750: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
6760: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
6770: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
6780: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
6790: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
67a0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
67b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
67c0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
67d0: 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f  *);.  /* Additio
67e0: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
67f0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
6800: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
6810: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
6820: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
6830: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
6840: 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30   {H11310} <S3080
6850: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  0>.**.** These i
6860: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
6870: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
6880: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
6890: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
68a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
68b0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
68c0: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
68d0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
68e0: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
68f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
6900: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
6910: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
6920: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
6930: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
6940: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
6950: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
6960: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
6970: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
6980: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
6990: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
69a0: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
69b0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
69c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
69d0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
69e0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
69f0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
6a00: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
6a10: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
6a20: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
6a30: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
6a40: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
6a50: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
6a60: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f  ng testing and o
6a70: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
6a80: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
6a90: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73  QLITE_TEST.** is
6aa0: 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65   defined..*/.#de
6ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
6ac0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
6ad0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6ae0: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
6af0: 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65  YFILE      2.#de
6b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
6b10: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
6b20: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6b30: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
6b40: 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a 2f 2a             4../*
6b50: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
6b60: 74 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31  tex Handle {H171
6b70: 31 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a  10} <S20130>.**.
6b80: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
6b90: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
6ba0: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
6bb0: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
6bc0: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
6bd0: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
6be0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
6bf0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
6c00: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
6c10: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
6c20: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
6c30: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
6c40: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
6c50: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
6c60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
6c70: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
6c80: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
6c90: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
6ca0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
6cb0: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
6cc0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6cd0: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
6ce0: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
6cf0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
6d00: 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34  ce Object {H1114
6d10: 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S20100>.**.*
6d20: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
6d30: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
6d40: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
6d50: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
6d60: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
6d70: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
6d80: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
6d90: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
6da0: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
6db0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
6dc0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
6dd0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
6de0: 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystem"..**.** Th
6df0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
6e00: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
6e10: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
6e20: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
6e30: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
6e40: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
6e50: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
6e60: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
6e70: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
6e80: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
6e90: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
6ea0: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
6eb0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
6ec0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
6ed0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
6ee0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
6ef0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
6f00: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
6f10: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
6f20: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
6f30: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
6f40: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
6f50: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
6f60: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
6f70: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
6f80: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
6f90: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
6fa0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
6fb0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
6fc0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
6fd0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
6fe0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
6ff0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
7000: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
7010: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
7020: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
7030: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
7040: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
7050: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
7060: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
7070: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
7080: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
7090: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
70a0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
70b0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
70c0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
70d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
70e0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
70f0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
7100: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
7110: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
7120: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
7130: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
7140: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
7150: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
7160: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
7170: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
7180: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
7190: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
71a0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
71b0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
71c0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
71d0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
71e0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
71f0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
7200: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
7210: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
7220: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
7230: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
7240: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
7250: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
7260: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
7270: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
7280: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
7290: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
72a0: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
72b0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
72c0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
72d0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
72e0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
72f0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
7300: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  les..**.** SQLit
7310: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
7320: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
7330: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
7340: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
7350: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
7360: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
7370: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
7380: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20  ullPathname().  
7390: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
73a0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
73b0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
73c0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
73d0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
73e0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
73f0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
7400: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
7410: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
7420: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
7430: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
7440: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
7450: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
7460: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
7470: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
7480: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
7490: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
74a0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
74b0: 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  is xOpen is a NU
74c0: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
74d0: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
74e0: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
74f0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
7500: 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65  the file.  Whene
7510: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
7520: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
7530: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
7540: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
7550: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
7560: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
7570: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
7580: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7590: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
75a0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
75b0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
75c0: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
75d0: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
75e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
75f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
7600: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
7610: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
7620: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
7630: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
7640: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
7650: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
7660: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
7670: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
7680: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
7690: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
76a0: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
76b0: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
76c0: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
76d0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
76e0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
76f0: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
7700: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
7710: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69   set..**.** SQLi
7720: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
7730: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
7740: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
7750: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
7760: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
7770: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
7780: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
7790: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
77a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
77b0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
77c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
77d0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
77e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
77f0: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
7800: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
7810: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
7820: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7830: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
7840: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7850: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
7860: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7870: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
7880: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  URNAL].** </ul>.
7890: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
78a0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
78b0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
78c0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
78d0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
78e0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
78f0: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
7900: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
7910: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
7920: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
7930: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
7940: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
7950: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
7960: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
7970: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
7980: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
7990: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
79a0: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
79b0: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
79c0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
79d0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
79e0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
79f0: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
7a00: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
7a10: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
7a20: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
7a30: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
7a40: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
7a50: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
7a60: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
7a70: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
7a80: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
7a90: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
7aa0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
7ab0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
7ac0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
7ad0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
7ae0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
7af0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7b00: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
7b10: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
7b20: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
7b30: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
7b40: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7b50: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
7b60: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
7b70: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
7b80: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
7b90: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
7ba0: 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b  s closed.  The [
7bb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
7bc0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
7bd0: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
7be0: 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a  MP  databases, j
7bf0: 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20  ournals and for 
7c00: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
7c10: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
7c20: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
7c30: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
7c40: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
7c50: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
7c60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7c70: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
7c80: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
7c90: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
7ca0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
7cb0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
7cc0: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
7cd0: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
7ce0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
7cf0: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
7d00: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
7d10: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
7d20: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
7d30: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7d40: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
7d50: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
7d60: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
7d70: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
7d80: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
7d90: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
7da0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
7db0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
7dc0: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
7dd0: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
7de0: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
7df0: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
7e00: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
7e10: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
7e20: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
7e30: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
7e40: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
7e50: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
7e60: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
7e70: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
7e80: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
7e90: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
7ea0: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
7eb0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
7ec0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
7ed0: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
7ee0: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
7ef0: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
7f00: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7f10: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
7f20: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
7f30: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7f40: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
7f50: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
7f60: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
7f70: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
7f80: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
7f90: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
7fa0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7fb0: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
7fc0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
7fd0: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
7fe0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
7ff0: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
8000: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
8010: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
8020: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
8030: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
8040: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
8050: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
8060: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
8070: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
8080: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
8090: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
80a0: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
80b0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
80c0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
80d0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
80e0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
80f0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
8100: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
8110: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
8120: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
8130: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
8140: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
8150: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
8160: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
8170: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
8180: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
8190: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
81a0: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
81b0: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
81c0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
81d0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
81e0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
81f0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
8200: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
8210: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
8220: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
8230: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
8240: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
8250: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
8260: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
8270: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
8280: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
8290: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
82a0: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
82b0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
82c0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
82d0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
82e0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
82f0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
8300: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
8310: 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72  eep(), and xCurr
8320: 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66  entTime() interf
8330: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
8340: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
8350: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
8360: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
8370: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
8380: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
8390: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
83a0: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
83b0: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
83c0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
83d0: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
83e0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
83f0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
8400: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
8410: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
8420: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
8430: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
8440: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
8450: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
8460: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
8470: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
8480: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
8490: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
84a0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
84b0: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
84c0: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
84d0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
84e0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
84f0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
8500: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
8510: 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a  and time..**.*/.
8520: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8530: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
8540: 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73  e3_vfs;.struct s
8550: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
8560: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
8570: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
8580: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
8590: 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f  ber */.  int szO
85a0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
85b0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
85c0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
85d0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
85e0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
85f0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
8600: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
8610: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
8620: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
8630: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
8640: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
8650: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
8660: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
8670: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
8680: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
8690: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
86a0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
86b0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
86c0: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
86d0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
86e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
86f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
8700: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
8710: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
8720: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
8730: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
8740: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
8750: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
8760: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
8770: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
8780: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
8790: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
87a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
87b0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
87c0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
87d0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
87e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
87f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8800: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
8810: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
8820: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
8830: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
8840: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
8850: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
8860: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
8870: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
8880: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
8890: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
88a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
88b0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
88c0: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
88d0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
88e0: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
88f0: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
8900: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
8910: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
8920: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
8930: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
8940: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
8950: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
8960: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
8970: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
8980: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
8990: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
89a0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
89b0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
89c0: 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20  ar *);.  /* New 
89d0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
89e0: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
89f0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
8a00: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
8a10: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
8a20: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
8a30: 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a   happens. */.};.
8a40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8a50: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
8a60: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
8a70: 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 31  d {H11190} <H111
8a80: 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  40>.**.** These 
8a90: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
8aa0: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
8ab0: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
8ac0: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
8ad0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
8ae0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
8af0: 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20  ] object. {END} 
8b00: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
8b10: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
8b20: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
8b30: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
8b40: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
8b50: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
8b60: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
8b70: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
8b80: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
8b90: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
8ba0: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
8bb0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
8bc0: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
8bd0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
8be0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
8bf0: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68  the file is both
8c00: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
8c10: 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 20  itable..** With 
8c20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8c30: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
8c40: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
8c50: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
8c60: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a  e is readable..*
8c70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8c80: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
8c90: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
8ca0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
8cb0: 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ITE 1.#define SQ
8cc0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8cd0: 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43        2../*.** C
8ce0: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
8cf0: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
8d00: 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d 20  ibrary {H10130} 
8d10: 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30 3e  <S20000><S30100>
8d20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
8d30: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
8d40: 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
8d50: 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
8d60: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
8d70: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
8d80: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
8d90: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
8da0: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
8db0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
8dc0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
8dd0: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
8de0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
8df0: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
8e00: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
8e10: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
8e20: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
8e30: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
8e40: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
8e50: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
8e60: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
8e70: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
8e80: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
8e90: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
8ea0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
8eb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8ec0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
8ed0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
8ee0: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
8ef0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
8f00: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
8f10: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
8f20: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
8f30: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
8f40: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
8f50: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
8f60: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
8f70: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
8f80: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
8f90: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
8fa0: 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74    Only an effect
8fb0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
8fc0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
8fd0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
8fe0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
8ff0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
9000: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
9010: 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  -ops..**.** A ca
9020: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
9030: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
9040: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
9050: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
9060: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
9070: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9080: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
9090: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
90a0: 7a 65 28 29 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 61  ze().  Only.** a
90b0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
90c0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
90d0: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
90e0: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
90f0: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
9100: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
9110: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9120: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
9130: 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  -ops..**.** 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 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
9160: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
9170: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
9180: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
9190: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
91a0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
91b0: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
91c0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
91d0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
91e0: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
91f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
9200: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
9210: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
9220: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
9230: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
9240: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
9250: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
9260: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
9270: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
9280: 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33 5f  things, sqlite3_
9290: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
92a0: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
92b0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
92c0: 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74  Similarly, sqlit
92d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
92e0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
92f0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
9300: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
9310: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9320: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
9330: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
9340: 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20  cess..** If for 
9350: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
9360: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9370: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
9380: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
9390: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
93a0: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
93b0: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
93c0: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
93d0: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
93e0: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
93f0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
9400: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
9410: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  K]..**.** The sq
9420: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9430: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
9440: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
9450: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
9460: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
9470: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
9480: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
9490: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
94a0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
94b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
94c0: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
94d0: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
94e0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
94f0: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
9500: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
9510: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
9520: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
9530: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
9540: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
9550: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
9560: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
9570: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
9580: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f  .** already.  Ho
9590: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
95a0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
95b0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
95c0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
95d0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
95e0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
95f0: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
9600: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9610: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
9620: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
9630: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
9640: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
9650: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
9660: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
9670: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
9680: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
9690: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
96a0: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
96b0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
96c0: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
96d0: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
96e0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
96f0: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
9700: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
9710: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
9720: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
9730: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
9740: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
9750: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
9760: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
9770: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
9780: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
9790: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
97a0: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
97b0: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
97c0: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
97d0: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
97e0: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
97f0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
9800: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9810: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
9820: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
9830: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
9840: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
9850: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
9860: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
9870: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
9880: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
9890: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
98a0: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
98b0: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
98c0: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
98d0: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
98e0: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
98f0: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
9900: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
9910: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
9920: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
9930: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
9940: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
9950: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
9960: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
9970: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
9980: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
9990: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
99a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
99b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
99c0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
99d0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
99e0: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
99f0: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
9a00: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
9a10: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
9a20: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
9a30: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
9a40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9a50: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
9a60: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
9a70: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9a80: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
9a90: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
9aa0: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
9ab0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
9ac0: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
9ad0: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
9ae0: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
9af0: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
9b00: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
9b10: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
9b20: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
9b30: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
9b40: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
9b50: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
9b60: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
9b70: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
9b80: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
9b90: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
9ba0: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
9bb0: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
9bc0: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
9bd0: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
9be0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
9bf0: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
9c00: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
9c10: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
9c20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
9c30: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
9c40: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
9c50: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
9c60: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
9c70: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
9c80: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
9c90: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
9ca0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
9cb0: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
9cc0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
9cd0: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
9ce0: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
9cf0: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
9d00: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
9d10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9d20: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
9d30: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
9d40: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
9d50: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
9d60: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
9d70: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
9d80: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
9d90: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
9da0: 4c 69 62 72 61 72 79 20 7b 48 31 34 31 30 30 7d  Library {H14100}
9db0: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30   <S20000><S30200
9dc0: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
9dd0: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  L.**.** The sqli
9de0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
9df0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
9e00: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
9e10: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
9e20: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
9e30: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
9e40: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
9e50: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
9e60: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
9e70: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
9e80: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
9e90: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
9ea0: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
9eb0: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
9ec0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
9ed0: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
9ee0: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
9ef0: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
9f00: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
9f10: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
9f20: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
9f30: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
9f40: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
9f50: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
9f60: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
9f70: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
9f80: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
9f90: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
9fa0: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
9fb0: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
9fc0: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
9fd0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
9fe0: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
9ff0: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
a000: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
a010: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
a020: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
a030: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
a040: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
a050: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
a060: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
a070: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
a080: 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  wn()]..** Note, 
a090: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 73 71  however, that sq
a0a0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
a0b0: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
a0c0: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
a0d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
a0e0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
a0f0: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
a100: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
a110: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
a120: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
a130: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
a140: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
a150: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
a160: 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75  THREAD | configu
a170: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
a180: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
a190: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
a1a0: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
a1b0: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
a1c0: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
a1d0: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
a1e0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53  ending on the [S
a1f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
a200: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
a210: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
a220: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
a230: 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
a240: 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75  * When a configu
a250: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
a260: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
a270: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
a280: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49  SQLITE_OK]..** I
a290: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
a2a0: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
a2b0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
a2c0: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
a2d0: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
a2e0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
a2f0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
a300: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  e]..**.** Requir
a310: 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 31  ements:.** [H141
a320: 30 33 5d 20 5b 48 31 34 31 30 36 5d 20 5b 48 31  03] [H14106] [H1
a330: 34 31 32 30 5d 20 5b 48 31 34 31 32 33 5d 20 5b  4120] [H14123] [
a340: 48 31 34 31 32 36 5d 20 5b 48 31 34 31 32 39 5d  H14126] [H14129]
a350: 20 5b 48 31 34 31 33 32 5d 20 5b 48 31 34 31 33   [H14132] [H1413
a360: 35 5d 0a 2a 2a 20 5b 48 31 34 31 33 38 5d 20 5b  5].** [H14138] [
a370: 48 31 34 31 34 31 5d 20 5b 48 31 34 31 34 34 5d  H14141] [H14144]
a380: 20 5b 48 31 34 31 34 37 5d 20 5b 48 31 34 31 35   [H14147] [H1415
a390: 30 5d 20 5b 48 31 34 31 35 33 5d 20 5b 48 31 34  0] [H14153] [H14
a3a0: 31 35 36 5d 20 5b 48 31 34 31 35 39 5d 0a 2a 2a  156] [H14159].**
a3b0: 20 5b 48 31 34 31 36 32 5d 20 5b 48 31 34 31 36   [H14162] [H1416
a3c0: 35 5d 20 5b 48 31 34 31 36 38 5d 0a 2a 2f 0a 53  5] [H14168].*/.S
a3d0: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
a3e0: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  AL int sqlite3_c
a3f0: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
a400: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a410: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
a420: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
a430: 20 20 7b 48 31 34 32 30 30 7d 20 3c 53 32 30 30    {H14200} <S200
a440: 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
a450: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  TAL.**.** The sq
a460: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
a470: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
a480: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
a490: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
a4a0: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
a4b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
a4c0: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
a4d0: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
a4e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
a4f0: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
a500: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
a510: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
a520: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
a530: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
a540: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
a550: 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a  rgument).  The.*
a560: 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  * sqlite3_db_con
a570: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
a580: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
a590: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
a5a0: 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  er.** the databa
a5b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
a5c0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
a5d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
a5e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
a5f0: 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  n16()], or [sqli
a600: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
a610: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f   .**.** The seco
a620: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
a630: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
a640: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
a650: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
a660: 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74  on verb - an int
a670: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69  eger code that i
a680: 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a  ndicates what.**
a690: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
a6a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a6b0: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
a6c0: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65  nfigured..** The
a6d0: 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72   only choice for
a6e0: 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b   this value is [
a6f0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
a700: 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e  LOOKASIDE]..** N
a710: 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b  ew verbs are lik
a720: 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64 20  ely to be added 
a730: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
a740: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
a750: 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   Additional argu
a760: 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20  ments depend on 
a770: 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  the verb..**.** 
a780: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
a790: 20 5b 48 31 34 32 30 33 5d 20 5b 48 31 34 32 30   [H14203] [H1420
a7a0: 36 5d 20 5b 48 31 34 32 30 39 5d 20 5b 48 31 34  6] [H14209] [H14
a7b0: 32 31 32 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f  212] [H14215].*/
a7c0: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
a7d0: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
a7e0: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
a7f0: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
a800: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
a810: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
a820: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b  ation Routines {
a830: 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e  H10155} <S20120>
a840: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
a850: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
a860: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
a870: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
a880: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
a890: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
a8a0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
a8b0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
a8c0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
a8d0: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
a8e0: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
a8f0: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
a900: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
a910: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
a920: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
a930: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
a940: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
a950: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
a960: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
a970: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
a980: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
a990: 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
a9a0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
a9b0: 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
a9c0: 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
a9d0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
a9e0: 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
a9f0: 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
aa00: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
aa10: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
aa20: 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
aa30: 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
aa40: 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
aa50: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
aa60: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
aa70: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
aa80: 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
aa90: 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
aaa0: 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
aab0: 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
aac0: 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
aad0: 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
aae0: 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
aaf0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
ab00: 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
ab10: 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
ab20: 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
ab30: 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
ab40: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
ab50: 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
ab60: 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
ab70: 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
ab80: 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
ab90: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
aba0: 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
abb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
abc0: 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
abd0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
abe0: 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
abf0: 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
ac00: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
ac10: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
ac20: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
ac30: 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
ac40: 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
ac50: 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
ac60: 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
ac70: 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
ac80: 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
ac90: 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
aca0: 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
acb0: 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
acc0: 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78  he xMalloc and x
acd0: 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
ace0: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
acf0: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ** malloc() and 
ad00: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
ad10: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
ad20: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
ad30: 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65   The xRealloc me
ad40: 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c  thod must work l
ad50: 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72  ike realloc() fr
ad60: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
ad70: 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74  C library.** wit
ad80: 68 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20  h the exception 
ad90: 74 68 61 74 20 69 66 20 74 68 65 20 73 65 63 6f  that if the seco
ada0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  nd argument to x
adb0: 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c  Realloc is zero,
adc0: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73  .** xRealloc mus
add0: 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69  t be a no-op - i
ade0: 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f  t must not perfo
adf0: 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f  rm any allocatio
ae00: 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  n or.** dealloca
ae10: 74 69 6f 6e 2e 20 20 53 51 4c 69 74 65 20 67 75  tion.  SQLite gu
ae20: 61 72 61 6e 74 65 65 64 73 20 74 68 61 74 20 74  aranteeds that t
ae30: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
ae40: 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
ae50: 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
ae60: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
ae70: 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
ae80: 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64  xRoundup..** And
ae90: 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65   so in cases whe
aea0: 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61  re xRoundup alwa
aeb0: 79 73 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ys returns a pos
aec0: 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a  itive number,.**
aed0: 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65   xRealloc can pe
aee0: 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73  rform exactly as
aef0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69   the standard li
af00: 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20  brary realloc() 
af10: 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20  and.** still be 
af20: 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69  in compliance wi
af30: 74 68 20 74 68 69 73 20 73 70 65 63 69 66 69 63  th this specific
af40: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  ation..**.** xSi
af50: 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
af60: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
af70: 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
af80: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
af90: 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
afa0: 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
afb0: 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
afc0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
afd0: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
afe0: 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
aff0: 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
b000: 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
b010: 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
b020: 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
b030: 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
b040: 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
b050: 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
b060: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b070: 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
b080: 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
b090: 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
b0a0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
b0b0: 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
b0c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
b0d0: 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
b0e0: 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
b0f0: 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
b100: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
b110: 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
b120: 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
b130: 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
b140: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b150: 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
b160: 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
b170: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
b180: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
b190: 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
b1a0: 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
b1b0: 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
b1c0: 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
b1d0: 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
b1e0: 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
b1f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
b200: 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
b210: 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
b220: 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
b230: 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
b240: 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
b250: 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
b260: 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
b270: 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
b280: 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
b290: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
b2a0: 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
b2b0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
b2c0: 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
b2d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
b2e0: 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
b2f0: 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
b300: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
b310: 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
b320: 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
b330: 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
b340: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
b350: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
b360: 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
b370: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
b380: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
b390: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
b3a0: 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
b3b0: 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
b3c0: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
b3d0: 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
b3e0: 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
b3f0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
b400: 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
b410: 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
b420: 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
b430: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
b440: 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
b450: 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
b460: 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
b470: 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
b480: 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
b490: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
b4a0: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
b4b0: 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
b4c0: 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
b4d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
b4e0: 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
b4f0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
b500: 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
b510: 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
b520: 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
b530: 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
b540: 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
b550: 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
b560: 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
b570: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
b580: 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
b590: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
b5a0: 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
b5b0: 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
b5c0: 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
b5d0: 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
b5e0: 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
b5f0: 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
b600: 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
b610: 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
b620: 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
b630: 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
b640: 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
b650: 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
b660: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
b670: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
b680: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b690: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
b6a0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
b6b0: 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
b6c0: 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
b6d0: 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
b6e0: 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
b6f0: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
b700: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
b710: 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
b720: 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
b730: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
b740: 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
b750: 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
b760: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
b770: 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
b780: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
b790: 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
b7a0: 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
b7b0: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
b7c0: 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
b7d0: 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
b7e0: 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
b7f0: 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
b800: 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
b810: 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
b820: 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
b830: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
b840: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
b850: 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
b860: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
b870: 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
b880: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
b890: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
b8a0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
b8b0: 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
b8c0: 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
b8d0: 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
b8e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
b8f0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
b900: 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36  n Options {H1016
b910: 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45  0} <S20000>.** E
b920: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
b930: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
b940: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
b950: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
b960: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
b970: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
b980: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
b990: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
b9a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
b9b0: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
b9c0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
b9d0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
b9e0: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
b9f0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
ba00: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
ba10: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
ba20: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
ba30: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
ba40: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
ba50: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
ba60: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
ba70: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
ba80: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
ba90: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
baa0: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
bab0: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
bac0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
bad0: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
bae0: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
baf0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
bb00: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
bb10: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
bb20: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bb30: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
bb40: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
bb50: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
bb60: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
bb70: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
bb80: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
bb90: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
bba0: 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69    This option di
bbb0: 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
bbc0: 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
bbd0: 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
bbe0: 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
bbf0: 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
bc00: 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
bc10: 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ad.</dd>.**.** <
bc20: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
bc30: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
bc40: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
bc50: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
bc60: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
bc70: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73   This option dis
bc80: 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
bc90: 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
bca0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
bcb0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
bcc0: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
bcd0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
bce0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
bcf0: 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
bd00: 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
bd10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bd20: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
bd30: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
bd40: 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
bd50: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
bd60: 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
bd70: 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
bd80: 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
bd90: 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
bda0: 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
bdb0: 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
bdc0: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
bdd0: 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
bde0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
bdf0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
be00: 65 2e 20 20 53 65 65 20 74 68 65 20 5b 74 68 72  e.  See the [thr
be10: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20  eading mode].** 
be20: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
be30: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
be40: 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  ormation.</dd>.*
be50: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
be60: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
be70: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
be80: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
be90: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
bea0: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f  ion.  This optio
beb0: 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
bec0: 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
bed0: 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
bee0: 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
bef0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
bf00: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
bf10: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
bf20: 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
bf30: 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
bf40: 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
bf50: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
bf60: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
bf70: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
bf80: 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
bf90: 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
bfa0: 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
bfb0: 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
bfc0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
bfd0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
bfe0: 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
bff0: 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
c000: 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
c010: 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
c020: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c030: 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
c040: 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
c050: 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
c060: 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
c070: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
c080: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61  * See the [threa
c090: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d  ding mode] docum
c0a0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
c0b0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
c0c0: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
c0d0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c0e0: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
c0f0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c100: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
c110: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
c120: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c130: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
c140: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
c150: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
c160: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
c170: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
c180: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
c190: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
c1a0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
c1b0: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
c1c0: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
c1d0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c1e0: 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
c1f0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64   into SQLite.</d
c200: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c210: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
c220: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
c230: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
c240: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
c250: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
c260: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
c270: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
c280: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
c290: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
c2a0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
c2b0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
c2c0: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
c2d0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
c2e0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
c2f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c300: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68   routines..** Th
c310: 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
c320: 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
c330: 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
c340: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
c350: 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
c360: 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
c370: 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
c380: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
c390: 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
c3a0: 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
c3b0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64   for example.</d
c3c0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c3d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
c3e0: 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
c3f0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
c400: 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
c410: 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20  nt of type int, 
c420: 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
c430: 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68   .** boolean, wh
c440: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
c450: 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
c460: 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
c470: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20   allocation .** 
c480: 73 74 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e  statistics. When
c490: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
c4a0: 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
c4b0: 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
c4c0: 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74  e .** non-operat
c4d0: 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
c4e0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c4f0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
c500: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
c510: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
c520: 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
c530: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
c540: 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a  t_heap_limit()].
c550: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
c560: 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
c570: 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e    </ul>.** </dd>
c580: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c590: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
c5a0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
c5b0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
c5c0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
c5d0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
c5e0: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
c5f0: 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
c600: 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
c610: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
c620: 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
c630: 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
c640: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
c650: 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
c660: 72 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  rach allocations
c670: 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
c680: 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
c690: 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
c6a0: 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
c6b0: 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
c6c0: 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
c6d0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
c6e0: 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
c6f0: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
c700: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
c710: 20 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   The sz paramete
c720: 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65  r should be a fe
c730: 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65  w bytes.** large
c740: 72 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61  r than the actua
c750: 6c 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20  l scratch space 
c760: 72 65 71 75 69 72 65 64 20 64 75 65 20 74 6f 20  required due to 
c770: 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61  internal overhea
c780: 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  d..** The first 
c790: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
c7a0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
c7b0: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
c7c0: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
c7d0: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
c7e0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69   memory..** SQLi
c7f0: 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
c800: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
c810: 61 74 63 68 20 62 75 66 66 65 72 20 61 74 20 6f  atch buffer at o
c820: 6e 63 65 20 70 65 72 20 74 68 72 65 61 64 2c 20  nce per thread, 
c830: 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  so.** N should b
c840: 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 70  e set to the exp
c850: 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
c860: 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
c870: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61    The sz.** para
c880: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
c890: 36 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65  6 times the size
c8a0: 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
c8b0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
c8c0: 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62  ze..** Scratch b
c8d0: 75 66 66 65 72 73 20 61 72 65 20 75 73 65 64 20  uffers are used 
c8e0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 62  as part of the b
c8f0: 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65  tree balance ope
c900: 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54  ration.  If.** T
c910: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65  he btree balance
c920: 72 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  r needs addition
c930: 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  al memory beyond
c940: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
c950: 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20  d by.** scratch 
c960: 62 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f  buffers or if no
c970: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
c980: 73 70 61 63 65 20 69 73 20 73 70 65 63 69 66 69  space is specifi
c990: 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  ed, then SQLite.
c9a0: 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  ** goes to [sqli
c9b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f  te3_malloc()] to
c9c0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
c9d0: 72 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64  ry it needs.</dd
c9e0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
c9f0: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
ca00: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
ca10: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
ca20: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
ca30: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
ca40: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
ca50: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
ca60: 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
ca70: 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
ca80: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
ca90: 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  emenation.  .** 
caa0: 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
cab0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
cac0: 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
cad0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
cae0: 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
caf0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
cb00: 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
cb10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
cb20: 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  ACHE option..** 
cb30: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
cb40: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
cb50: 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e  s option: A poin
cb60: 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c  ter to 8-byte al
cb70: 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
cb80: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
cb90: 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
cba0: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
cbb0: 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
cbc0: 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
cbd0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
cbe0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
cbf0: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
cc00: 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
cc10: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
cc20: 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c  12 and 32768) pl
cc30: 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72  us a little extr
cc40: 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  a for each.** pa
cc50: 67 65 20 68 65 61 64 65 72 2e 20 20 54 68 65 20  ge header.  The 
cc60: 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
cc70: 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
cc80: 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
cc90: 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
cca0: 69 74 65 63 74 75 72 65 2e 20 20 49 74 20 69 73  itecture.  It is
ccb0: 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
ccc0: 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
ccd0: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
cce0: 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
ccf0: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
cd00: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
cd10: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
cd20: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
cd30: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
cd40: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
cd50: 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  ..** SQLite will
cd60: 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
cd70: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
cd80: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
cd90: 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
cda0: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
cdb0: 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
cdc0: 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
cdd0: 20 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61   to cache.  If a
cde0: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
cdf0: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
ce00: 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
ce10: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
ce20: 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
ce30: 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
ce40: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
ce50: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
ce60: 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
ce70: 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
ce80: 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
ce90: 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65  on might use one
cea0: 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20   or more of the 
ceb0: 4e 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c  N buffers to hol
cec0: 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63  d .** memory acc
ced0: 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74  ounting informat
cee0: 69 6f 6e 2e 20 54 68 65 20 70 6f 69 6e 74 65 72  ion. The pointer
cef0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
cf00: 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
cf10: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
cf20: 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
cf30: 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
cf40: 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
cf50: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
cf60: 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
cf70: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
cf80: 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
cf90: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
cfa0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
cfb0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
cfc0: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
cfd0: 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
cfe0: 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
cff0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d000: 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
d010: 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
d020: 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
d030: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
d040: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
d050: 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
d060: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
d070: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
d080: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
d090: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
d0a0: 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
d0b0: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
d0c0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
d0d0: 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
d0e0: 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
d0f0: 69 7a 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  ize..** If the f
d100: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
d110: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
d120: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
d130: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
d140: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
d150: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
d160: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
d170: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
d180: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
d190: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
d1a0: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
d1b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
d1c0: 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65  MALLOC].  If the
d1d0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
d1e0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
d1f0: 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
d200: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
d210: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
d220: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
d230: 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
d240: 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
d250: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
d260: 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
d270: 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
d280: 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
d290: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
d2a0: 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
d2b0: 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
d2c0: 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
d2d0: 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
d2e0: 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
d2f0: 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
d300: 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
d310: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
d320: 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
d330: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
d340: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
d350: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
d360: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
d370: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
d380: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
d390: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
d3a0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
d3b0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
d3c0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
d3d0: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
d3e0: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
d3f0: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
d400: 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
d410: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
d420: 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
d430: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
d440: 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a   SQLite.</dd>.**
d450: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d460: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
d470: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
d480: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
d490: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
d4a0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
d4b0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
d4c0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
d4d0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
d4e0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
d4f0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
d500: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
d510: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
d520: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
d530: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
d540: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a  mutex routines..
d550: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
d560: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
d570: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
d580: 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
d590: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
d5a0: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
d5b0: 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
d5c0: 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
d5d0: 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
d5e0: 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
d5f0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f  , for example.</
d600: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d610: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
d620: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
d630: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
d640: 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
d650: 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
d660: 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
d670: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d680: 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69  n lookaside opti
d690: 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66  mization.  The f
d6a0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
d6b0: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
d6c0: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
d6d0: 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
d6e0: 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
d6f0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
d700: 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
d710: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
d720: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
d730: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
d740: 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  .** <i>default</
d750: 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
d760: 65 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  e.  The [SQLITE_
d770: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
d780: 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b  DE].** verb to [
d790: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
d7a0: 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
d7b0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
d7c0: 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
d7d0: 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
d7e0: 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
d7f0: 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ons.</dd>.**.** 
d800: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
d810: 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  G_PCACHE</dt>.**
d820: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
d830: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
d840: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
d850: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
d860: 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
d870: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
d880: 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
d890: 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
d8a0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
d8b0: 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
d8c0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
d8d0: 69 6f 6e 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b  ion.  SQLite mak
d8e0: 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
d8f0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
d900: 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
d910: 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
d920: 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
d930: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
d940: 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
d950: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
d960: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
d970: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
d980: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
d990: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
d9a0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
d9b0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53  hods] object.  S
d9c0: 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
d9d0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
d9e0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
d9f0: 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
da00: 61 74 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  at object.</dd>.
da10: 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
da20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
da30: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
da40: 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
da50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
da60: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
da70: 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
da80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
da90: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
daa0: 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
dab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dac0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
dad0: 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
dae0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
daf0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
db00: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
db10: 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
db20: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
db30: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
db40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
db50: 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
db60: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
db70: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
db80: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
db90: 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
dba0: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
dbb0: 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
dbc0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
dbd0: 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
dbe0: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
dbf0: 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
dc00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc10: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
dc20: 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
dc30: 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
dc40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
dc50: 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
dc60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
dc70: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
dc80: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
dc90: 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
dca0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
dcb0: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
dcc0: 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
dcd0: 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
dce0: 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
dcf0: 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
dd00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dd10: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
dd20: 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
dd30: 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
dd40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
dd50: 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
dd60: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
dd70: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
dd80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
dd90: 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
dda0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
ddb0: 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  che_methods* */.
ddc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ddd0: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
dde0: 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20  ptions {H10170} 
ddf0: 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45  <S20000>.** EXPE
de00: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
de10: 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
de20: 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
de30: 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
de40: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
de50: 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
de60: 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
de70: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
de80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
de90: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
dea0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
deb0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
dec0: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
ded0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
dee0: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
def0: 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
df00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
df10: 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
df20: 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
df30: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
df40: 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
df50: 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
df60: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
df70: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
df80: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
df90: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
dfa0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
dfb0: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
dfc0: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
dfd0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
dfe0: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
dff0: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
e000: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
e010: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
e020: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
e030: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
e040: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
e050: 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
e060: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e070: 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
e080: 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
e090: 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
e0a0: 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
e0b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
e0c0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
e0d0: 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
e0e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
e0f0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
e100: 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
e110: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
e120: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
e130: 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
e140: 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62  r to an memory b
e150: 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
e160: 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
e170: 79 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  y..** The first 
e180: 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
e190: 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
e1a0: 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
e1b0: 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
e1c0: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
e1d0: 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
e1e0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
e1f0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
e200: 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
e210: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
e220: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
e230: 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ot and the third
e240: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
e250: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
e260: 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
e270: 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
e280: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e290: 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
e2a0: 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
e2b0: 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
e2c0: 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
e2d0: 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
e2e0: 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
e2f0: 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
e300: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
e310: 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 49 66 20  e boundary.  If 
e320: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
e330: 65 6e 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 61 20  ent is not.** a 
e340: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
e350: 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 20  t is internally 
e360: 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
e370: 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
e380: 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  .** multiple of 
e390: 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53  8.  See also: [S
e3a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
e3b0: 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a  KASIDE]</dd>.**.
e3c0: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
e3d0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
e3e0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
e3f0: 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
e400: 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
e410: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
e420: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
e430: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
e440: 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53  odes {H12200} <S
e450: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
e460: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
e470: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
e480: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
e490: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
e4a0: 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
e4b0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
e4c0: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54  ure of SQLite. T
e4d0: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
e4e0: 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
e4f0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
e500: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
e510: 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
e520: 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e   considerations.
e530: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
e540: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 30 31 5d  nts:.** [H12201]
e550: 20 5b 48 31 32 32 30 32 5d 0a 2a 2f 0a 69 6e 74   [H12202].*/.int
e560: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
e570: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
e580: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
e590: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
e5a0: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
e5b0: 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d  t Rowid {H12220}
e5c0: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
e5d0: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
e5e0: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
e5f0: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
e600: 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
e610: 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
e620: 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
e630: 69 64 22 5d 2e 20 54 68 65 20 72 6f 77 69 64 20  id"]. The rowid 
e640: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
e650: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
e660: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
e670: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
e680: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
e690: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
e6a0: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
e6b0: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
e6c0: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
e6d0: 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68  olumns. If.** th
e6e0: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
e6f0: 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
e700: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
e710: 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
e720: 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
e730: 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
e740: 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rowid..**.** Thi
e750: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
e760: 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
e770: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
e780: 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
e790: 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
e7a0: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
e7b0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
e7c0: 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
e7d0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e7e0: 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73  t.  If no succes
e7f0: 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a  sful [INSERT]s.*
e800: 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
e810: 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74  rred on that dat
e820: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e830: 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
e840: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
e850: 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
e860: 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
e870: 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69  , then the [rowi
e880: 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
e890: 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74  ed.** row is ret
e8a0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
e8b0: 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73  utine as long as
e8c0: 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
e8d0: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
e8e0: 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
e8f0: 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
e900: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
e910: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  by this routine.
e920: 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ** reverts to th
e930: 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
e940: 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
e950: 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a   trigger fired..
e960: 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54  **.** An [INSERT
e970: 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
e980: 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
e990: 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
e9a0: 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
e9b0: 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
e9c0: 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
e9d0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
e9e0: 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
e9f0: 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45  tine.  Thus INSE
ea00: 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
ea10: 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
ea20: 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
ea30: 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
ea40: 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
ea50: 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
ea60: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
ea70: 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
ea80: 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
ea90: 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65  tion fails.  Whe
eaa0: 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
eab0: 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
eac0: 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
ead0: 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
eae0: 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
eaf0: 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
eb00: 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
eb10: 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
eb20: 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
eb30: 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
eb40: 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
eb50: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
eb60: 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
eb70: 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
eb80: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
eb90: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
eba0: 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
ebb0: 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
ebc0: 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
ebd0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
ebe0: 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
ebf0: 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
ec00: 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
ec10: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
ec20: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
ec30: 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
ec40: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
ec50: 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
ec60: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
ec70: 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
ec80: 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
ec90: 0a 2a 2a 20 5b 48 31 32 32 32 31 5d 20 5b 48 31  .** [H12221] [H1
eca0: 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61  2223].**.** If a
ecb0: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
ecc0: 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
ecd0: 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
ece0: 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
ecf0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
ed00: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
ed10: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
ed20: 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
ed30: 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
ed40: 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
ed50: 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
ed60: 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
ed70: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
ed80: 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
ed90: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
eda0: 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
edb0: 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
edc0: 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
edd0: 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
ede0: 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
edf0: 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
ee00: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
ee10: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
ee20: 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
ee30: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ee40: 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
ee50: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
ee60: 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53 31  ied {H12240} <S1
ee70: 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0600>.**.** This
ee80: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
ee90: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
eea0: 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
eeb0: 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
eec0: 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
eed0: 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
eee0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
eef0: 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
ef00: 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
ef10: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ef20: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
ef30: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
ef40: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79  rameter..** Only
ef50: 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
ef60: 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
ef70: 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
ef80: 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
ef90: 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
efa0: 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
efb0: 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
efc0: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
efd0: 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
efe0: 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
eff0: 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
f000: 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65  counted. Use the
f010: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
f020: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
f030: 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
f040: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
f050: 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
f060: 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
f070: 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
f080: 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
f090: 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
f0a0: 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
f0b0: 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
f0c0: 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
f0d0: 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
f0e0: 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
f0f0: 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
f100: 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
f110: 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
f120: 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
f130: 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
f140: 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
f150: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
f160: 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
f170: 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
f180: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
f190: 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
f1a0: 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
f1b0: 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
f1c0: 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
f1d0: 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
f1e0: 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
f1f0: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
f200: 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
f210: 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
f220: 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
f230: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
f240: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
f250: 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
f260: 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
f270: 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
f280: 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
f290: 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
f2a0: 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
f2b0: 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
f2c0: 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
f2d0: 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
f2e0: 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
f2f0: 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
f300: 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
f310: 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
f320: 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
f330: 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
f340: 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
f350: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
f360: 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
f370: 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
f380: 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
f390: 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
f3a0: 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
f3b0: 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
f3c0: 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
f3d0: 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
f3e0: 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  n..**.** Calling
f3f0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
f400: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
f410: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
f420: 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
f430: 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
f440: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
f450: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
f460: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
f470: 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
f480: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
f490: 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
f4a0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
f4b0: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
f4c0: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
f4d0: 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
f4e0: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75  ntext..**.** Thu
f4f0: 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
f500: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
f510: 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
f520: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
f530: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
f540: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
f550: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
f560: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
f570: 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
f580: 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
f590: 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74  level.  Within t
f5a0: 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
f5b0: 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
f5c0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
f5d0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
f5e0: 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
f5f0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
f600: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
f610: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
f620: 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
f630: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
f640: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
f650: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
f660: 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
f670: 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
f680: 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
f690: 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
f6a0: 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
f6b0: 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
f6c0: 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
f6d0: 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
f6e0: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53  context..**.** S
f6f0: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
f700: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
f710: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
f720: 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
f730: 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
f740: 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
f750: 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
f760: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
f770: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34 31  ents:.** [H12241
f780: 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a  ] [H12243].**.**
f790: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
f7a0: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
f7b0: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
f7c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f7d0: 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
f7e0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
f7f0: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
f800: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
f810: 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
f820: 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
f830: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
f840: 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
f850: 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
f860: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
f870: 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
f880: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31  ows Modified {H1
f890: 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a  2260} <S10600>.*
f8a0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
f8b0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
f8c0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
f8d0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
f8e0: 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
f8f0: 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
f900: 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
f910: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
f920: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
f930: 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63  opened..** The c
f940: 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c  ount includes al
f950: 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61  l changes from a
f960: 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
f970: 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 0a 2a  ER | trigger] .*
f980: 2a 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63  * contexts and c
f990: 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 20 5b  hanges made by [
f9a0: 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
f9b0: 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a  ons]. However,.*
f9c0: 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
f9d0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
f9e0: 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
f9f0: 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d  lement [REPLACE]
fa00: 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
fa10: 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
fa20: 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
fa30: 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c  g, or [DROP TABL
fa40: 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20  E] processing.  
fa50: 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65  The.** count doe
fa60: 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f  s not include ro
fa70: 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74  ws of views that
fa80: 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41   fire an [INSTEA
fa90: 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a  D OF trigger],.*
faa0: 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20  * though if the 
fab0: 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
fac0: 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  er makes changes
fad0: 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f   of its own, tho
fae0: 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61  se changes .** a
faf0: 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 54  re counted..** T
fb00: 68 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  he changes are c
fb10: 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  ounted as soon a
fb20: 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
fb30: 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
fb40: 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  is.** completed 
fb50: 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
fb60: 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61  ent handle is pa
fb70: 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
fb80: 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
fb90: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
fba0: 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
fbb0: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
fbc0: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
fbd0: 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
fbe0: 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
fbf0: 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
fc00: 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
fc10: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
fc20: 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
fc30: 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36 31 5d 20  ts:.** [H12261] 
fc40: 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a 2a 20 49  [H12263].**.** I
fc50: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
fc60: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
fc70: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
fc80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fc90: 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
fca0: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
fcb0: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
fcc0: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
fcd0: 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
fce0: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
fcf0: 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
fd00: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
fd10: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
fd20: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
fd30: 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
fd40: 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
fd50: 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d  g Query {H12270}
fd60: 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30500>.**.** 
fd70: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
fd80: 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
fd90: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
fda0: 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
fdb0: 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
fdc0: 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
fdd0: 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
fde0: 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
fdf0: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
fe00: 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
fe10: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
fe20: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
fe30: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
fe40: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
fe50: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
fe60: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
fe70: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
fe80: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
fe90: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
fea0: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
feb0: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
fec0: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
fed0: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
fee0: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
fef0: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
ff00: 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
ff10: 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
ff20: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
ff30: 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
ff40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ff50: 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
ff60: 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
ff70: 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
ff80: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
ff90: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
ffa0: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
ffb0: 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
ffc0: 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
ffd0: 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
ffe0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
fff0: 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
10000 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
10010 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
10020 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
10030 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
10040 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
10050 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  etion..**.** An 
10060 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
10070 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
10080 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
10090 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
100a0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
100b0 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
100c0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
100d0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
100e0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
100f0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
10100 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
10110 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
10120 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
10130 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
10140 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
10150 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
10160 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
10170 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
10180 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
10190 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
101a0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
101b0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
101c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
101d0 70 6c 65 74 65 2e 20 20 41 6e 79 20 6e 65 77 20  plete.  Any new 
101e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
101f0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
10200 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
10210 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
10220 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
10230 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
10240 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
10250 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
10260 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
10270 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
10280 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
10290 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
102a0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
102b0 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
102c0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
102d0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
102e0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
102f0 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
10300 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
10310 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
10320 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
10330 70 74 28 29 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20  pt()..** A call 
10340 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
10350 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
10360 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
10370 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
10380 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
10390 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
103a0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
103b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
103c0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
103d0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
103e0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
103f0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
10400 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
10410 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31 5d 20 5b  s:.** [H12271] [
10420 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a 20 49 66  H12272].**.** If
10430 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
10440 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
10450 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
10460 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
10470 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
10480 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
10490 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
104a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
104b0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
104c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
104d0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
104e0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
104f0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 48  t Is Complete {H
10500 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e 0a  10510} <S70200>.
10510 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
10520 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
10530 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
10540 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
10550 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
10560 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
10570 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
10580 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
10590 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
105a0 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
105b0 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
105c0 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
105d0 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
105e0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
105f0 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f  rsing.  These ro
10600 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
10610 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
10620 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
10630 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
10640 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
10650 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
10660 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
10670 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
10680 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
10690 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
106a0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
106b0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
106c0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
106d0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d   statement.  Sem
106e0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
106f0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
10700 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
10710 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
10720 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
10730 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
10740 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
10750 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
10760 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
10770 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
10780 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
10790 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
107a0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
107b0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
107c0 74 6f 72 2e 20 20 57 68 69 74 65 73 70 61 63 65  tor.  Whitespace
107d0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
107e0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
107f0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
10800 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
10810 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
10820 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
10830 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
10840 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 49 66 20  incomplete.  If 
10850 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
10860 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
10870 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
10880 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
10890 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
108a0 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
108b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
108c0 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
108d0 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
108e0 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
108f0 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  t SQL..**.** If 
10900 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
10910 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
10920 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
10930 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
10940 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
10950 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
10960 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
10970 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10980 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
10990 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
109a0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
109b0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
109c0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
109d0 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
109e0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
109f0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
10a00 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
10a10 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
10a20 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
10a30 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
10a40 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
10a50 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ete..**.** Requi
10a60 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35 31 31  rements: [H10511
10a70 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a 0a 2a 2a  ] [H10512].**.**
10a80 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
10a90 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
10aa0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
10ab0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
10ac0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
10ad0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
10ae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
10af0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
10b00 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
10b10 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
10b20 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
10b30 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
10b40 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
10b50 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
10b60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
10b70 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
10b80 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
10b90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
10ba0 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
10bb0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
10bc0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48  E_BUSY Errors {H
10bd0 31 32 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a  12310} <S40400>.
10be0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
10bf0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
10c00 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
10c10 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
10c20 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
10c30 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
10c40 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
10c50 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
10c60 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
10c70 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
10c80 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  locked..**.** If
10c90 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
10ca0 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
10cb0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
10cc0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
10cd0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
10ce0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
10cf0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
10d00 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
10d10 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
10d20 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
10d30 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
10d40 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69  llback will be i
10d50 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
10d60 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
10d70 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
10d80 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c  ent to the handl
10d90 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
10da0 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
10db0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
10dc0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
10dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
10de0 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65  _handler().  The
10df0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10e00 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c   to.** the handl
10e10 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
10e20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
10e30 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
10e40 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
10e50 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
10e60 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
10e70 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  ent.  If the.** 
10e80 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
10e90 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
10ea0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
10eb0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
10ec0 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
10ed0 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
10ee0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
10ef0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
10f00 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
10f10 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62  .** If the callb
10f20 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
10f30 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
10f40 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
10f50 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68   made to open th
10f60 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
10f70 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63  eading and the c
10f80 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
10f90 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
10fa0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
10fb0 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
10fc0 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
10fd0 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
10fe0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
10ff0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
11000 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
11010 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
11020 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
11030 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
11040 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
11050 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
11060 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
11070 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
11080 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
11090 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
110a0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
110b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
110c0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
110d0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
110e0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
110f0 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
11100 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
11110 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
11120 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
11130 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
11140 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
11150 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
11160 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
11170 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
11180 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
11190 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
111a0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
111b0 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
111c0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
111d0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
111e0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
111f0 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
11200 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
11210 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
11220 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
11230 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
11240 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
11250 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
11260 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
11270 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
11280 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
11290 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
112a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
112b0 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
112c0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
112d0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
112e0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
112f0 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
11300 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
11310 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
11320 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
11330 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
11340 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75  * The default bu
11350 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
11360 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
11370 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
11380 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
11390 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
113a0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
113b0 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
113c0 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
113d0 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
113e0 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
113f0 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
11400 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
11410 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
11420 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
11430 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
11440 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
11450 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
11460 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
11470 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
11480 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
11490 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
114a0 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
114b0 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
114c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
114d0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
114e0 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
114f0 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69  eaders.  If it i
11500 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
11510 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
11520 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
11530 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
11540 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
11550 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
11560 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
11570 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
11580 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
11590 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
115a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
115b0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
115c0 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
115d0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69  R_BLOCKED].  Thi
115e0 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
115f0 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
11600 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
11610 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
11620 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
11630 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
11640 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
11650 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
11660 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
11670 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
11680 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
11690 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
116a0 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
116b0 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
116c0 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rtant..**.** The
116d0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
116e0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
116f0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
11700 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
11710 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
11720 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
11730 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
11740 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
11750 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
11760 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c  .  Note that cal
11770 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
11780 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
11790 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
117a0 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
117b0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
117c0 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
117d0 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
117e0 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
117f0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
11800 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
11810 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
11820 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
11830 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
11840 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
11850 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
11860 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 52  havior..** .** R
11870 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
11880 5b 48 31 32 33 31 31 5d 20 5b 48 31 32 33 31 32  [H12311] [H12312
11890 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48 31 32 33  ] [H12314] [H123
118a0 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a 2a 2a 0a  16] [H12318].**.
118b0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
118c0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
118d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
118e0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
118f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11900 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
11910 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
11920 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
11930 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
11940 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
11950 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
11960 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
11970 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
11980 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d  Timeout {H12340}
11990 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
119a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
119b0 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
119c0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
119d0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
119e0 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
119f0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
11a00 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
11a10 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
11a20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20   The handler.** 
11a30 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
11a40 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
11a50 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
11a60 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
11a70 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
11a80 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32  ccumulated. {H12
11a90 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20  343} After "ms" 
11aa0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
11ab0 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
11ac0 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
11ad0 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
11ae0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
11af0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
11b00 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
11b10 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
11b20 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  CKED]..**.** Cal
11b30 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
11b40 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
11b50 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
11b60 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
11b70 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
11b80 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
11b90 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
11ba0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
11bb0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
11bc0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
11bd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11be0 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
11bf0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
11c00 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
11c10 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
11c20 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
11c30 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
11c40 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
11c50 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
11c60 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
11c70 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
11c80 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a  is cleared..**.*
11c90 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
11ca0 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b 48 31 32  ** [H12341] [H12
11cb0 33 34 33 5d 20 5b 48 31 32 33 34 34 5d 0a 2a 2f  343] [H12344].*/
11cc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
11cd0 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
11ce0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
11cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11d00 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
11d10 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
11d20 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20  ueries {H12370} 
11d30 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44  <S10000>.**.** D
11d40 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
11d50 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
11d60 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
11d70 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
11d80 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
11d90 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11da0 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
11db0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
11dc0 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
11dd0 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
11de0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
11df0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
11e00 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
11e10 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
11e20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
11e30 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
11e40 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
11e50 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
11e60 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
11e70 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
11e80 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
11e90 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
11ea0 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
11eb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
11ec0 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
11ed0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
11ee0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
11ef0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
11f00 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
11f10 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
11f20 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
11f30 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
11f40 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
11f50 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
11f60 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
11f70 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
11f80 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
11f90 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
11fa0 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
11fb0 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
11fc0 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
11fd0 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
11fe0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
11ff0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
12000 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
12010 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
12020 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
12030 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
12040 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
12050 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
12060 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
12070 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
12080 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
12090 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
120a0 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
120b0 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
120c0 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
120d0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
120e0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
120f0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
12100 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
12110 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
12120 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
12130 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
12140 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
12150 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
12160 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
12170 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
12180 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
12190 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
121a0 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
121b0 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
121c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
121d0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
121e0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
121f0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
12200 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
12210 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
12220 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
12230 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
12240 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
12250 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
12260 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
12270 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
12280 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
12290 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
122a0 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
122b0 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
122c0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
122d0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
122e0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
122f0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
12300 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
12310 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
12320 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
12330 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
12340 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
12350 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12360 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
12370 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
12380 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
12390 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
123a0 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
123b0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
123c0 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
123d0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
123e0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
123f0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
12400 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
12410 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12420 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
12430 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
12440 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
12450 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
12460 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12470 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
12480 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
12490 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
124a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
124b0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
124c0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
124d0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
124e0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
124f0 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
12500 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
12510 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
12520 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
12530 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
12540 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
12550 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
12560 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
12570 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
12580 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
12590 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
125a0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
125b0 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
125c0 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65  ould.** pass the
125d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
125e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
125f0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
12600 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
12610 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
12620 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
12630 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
12640 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
12650 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
12660 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
12670 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
12680 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
12690 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
126a0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
126b0 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
126c0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
126d0 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
126e0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
126f0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
12700 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
12710 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
12720 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
12730 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
12740 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
12750 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
12760 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
12770 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
12780 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
12790 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
127a0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
127b0 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
127c0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
127d0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
127e0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
127f0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
12800 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
12810 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
12820 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
12830 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
12840 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
12850 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
12860 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
12870 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
12880 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
12890 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
128a0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
128b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
128c0 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71  rrcode()] or [sq
128d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
128e0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
128f0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 37 31 5d  nts:.** [H12371]
12900 20 5b 48 31 32 33 37 33 5d 20 5b 48 31 32 33 37   [H12373] [H1237
12910 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b 48 31 32  4] [H12376] [H12
12920 33 37 39 5d 20 5b 48 31 32 33 38 32 5d 0a 2a 2f  379] [H12382].*/
12930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
12940 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
12950 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
12960 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
12970 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
12980 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
12990 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
129a0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
129b0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
129c0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
129d0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
129e0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
129f0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
12a00 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
12a10 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
12a20 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
12a30 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
12a40 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
12a50 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
12a60 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
12a70 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
12a80 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
12a90 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
12aa0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
12ab0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
12ac0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12ad0 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
12ae0 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
12af0 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c  tions {H17400} <
12b00 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a  S70000><S20000>.
12b10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
12b20 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
12b30 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
12b40 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
12b50 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
12b60 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
12b70 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
12b80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72   The sqlite3_mpr
12b90 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
12ba0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
12bb0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
12bc0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
12bd0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
12be0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
12bf0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
12c00 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
12c10 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
12c20 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
12c30 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
12c40 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
12c50 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69  ()].  Both routi
12c60 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
12c70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
12c80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12c90 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
12ca0 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
12cb0 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
12cc0 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
12cd0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
12ce0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
12cf0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
12d00 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
12d10 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
12d20 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12d30 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
12d40 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
12d50 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
12d60 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
12d70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12d80 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
12d90 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
12da0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
12db0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
12dc0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
12dd0 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
12de0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
12df0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
12e00 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
12e10 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
12e20 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
12e30 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
12e40 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
12e50 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
12e60 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f  lity.  Note also
12e70 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
12e80 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
12e90 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
12ea0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
12eb0 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
12ec0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
12ed0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
12ee0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
12ef0 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74  fer.  We admit t
12f00 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
12f10 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
12f20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
12f30 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
12f40 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
12f50 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
12f60 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
12f70 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
12f80 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
12f90 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
12fa0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
12fb0 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e  ty..**.** As lon
12fc0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
12fd0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
12fe0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
12ff0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
13000 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
13010 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
13020 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
13030 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73  nated.  The firs
13040 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
13050 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
13060 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
13070 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
13080 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
13090 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
130a0 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
130b0 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
130c0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
130d0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
130e0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
130f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
13100 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
13110 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
13120 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
13130 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
13140 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
13150 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
13160 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
13170 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
13180 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
13190 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
131a0 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
131b0 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
131c0 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
131d0 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
131e0 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
131f0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
13200 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
13210 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
13220 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
13230 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
13240 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
13250 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
13260 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
13270 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
13280 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
13290 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
132a0 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
132b0 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
132c0 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
132d0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
132e0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
132f0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
13300 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
13310 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
13320 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
13330 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
13340 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
13350 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
13360 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
13370 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13380 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
13390 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
133a0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
133b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
133c0 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
133d0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
133e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
133f0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
13400 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
13410 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
13420 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
13430 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
13440 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
13450 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
13460 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
13470 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
13480 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
13490 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
134a0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
134b0 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
134c0 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
134d0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
134e0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
134f0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
13500 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
13510 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
13520 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
13530 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13540 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
13550 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
13560 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
13570 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
13580 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
13590 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
135a0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
135b0 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
135c0 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
135d0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
135e0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
135f0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
13600 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
13610 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
13620 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
13630 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
13640 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
13650 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
13660 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
13670 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
13680 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
13690 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
136a0 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
136b0 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
136c0 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
136d0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
136e0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
136f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f  ..**.** The %Q o
13700 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
13710 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
13720 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
13730 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
13740 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
13750 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
13760 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
13770 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
13780 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
13790 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
137a0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
137b0 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
137c0 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
137d0 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
137e0 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
137f0 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
13800 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
13810 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
13820 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
13830 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
13840 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
13850 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
13860 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
13870 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
13880 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
13890 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
138a0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
138b0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
138c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
138d0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
138e0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
138f0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
13900 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
13910 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
13920 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
13930 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
13940 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
13950 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
13960 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
13970 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61  option works exa
13980 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77  ctly like "%s" w
13990 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
139a0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
139b0 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
139c0 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
139d0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
139e0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
139f0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
13a00 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
13a10 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  tring. {END}.**.
13a20 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
13a30 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20 5b 48 31  .** [H17403] [H1
13a40 37 34 30 36 5d 20 5b 48 31 37 34 30 37 5d 0a 2a  7406] [H17407].*
13a50 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
13a60 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
13a70 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
13a80 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
13a90 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
13aa0 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
13ab0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
13ac0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
13ad0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
13ae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
13af0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
13b00 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30  ubsystem {H17300
13b10 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
13b20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
13b30 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72    uses these thr
13b40 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
13b50 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
13b60 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
13b70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13b80 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
13b90 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
13ba0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
13bb0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
13bc0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
13bd0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
13be0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
13bf0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
13c00 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
13c10 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
13c20 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
13c30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
13c40 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
13c50 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
13c60 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
13c70 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
13c80 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
13c90 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
13ca0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
13cb0 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
13cc0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
13cd0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
13ce0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
13cf0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
13d00 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
13d10 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d  r.  If the param
13d20 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
13d30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
13d40 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
13d50 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
13d60 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
13d70 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
13d80 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  r..**.** Calling
13d90 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
13da0 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
13db0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
13dc0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
13dd0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
13de0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
13df0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
13e00 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
13e10 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
13e20 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
13e30 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
13e40 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
13e50 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
13e60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
13e70 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
13e80 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
13e90 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
13ea0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
13eb0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
13ec0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
13ed0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
13ee0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
13ef0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
13f00 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
13f10 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
13f20 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
13f30 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
13f40 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
13f50 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
13f60 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
13f70 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
13f80 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
13f90 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
13fa0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
13fb0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
13fc0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
13fd0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
13fe0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
13ff0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
14000 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
14010 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
14020 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61   The sqlite3_rea
14030 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
14040 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
14050 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
14060 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14070 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
14080 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
14090 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
140a0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
140b0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
140c0 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
140d0 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
140e0 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  * parameter.  If
140f0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14100 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
14110 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
14120 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
14130 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
14140 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
14150 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
14160 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
14170 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
14180 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
14190 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
141a0 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65  ()..** If the se
141b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
141c0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
141d0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
141e0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
141f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
14200 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
14210 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
14220 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
14230 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
14240 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14250 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14260 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  ()..** sqlite3_r
14270 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
14280 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
14290 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
142a0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
142b0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
142c0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
142d0 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
142e0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
142f0 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a   If M is the siz
14300 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
14310 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
14320 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
14330 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
14340 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
14350 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
14360 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
14370 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
14380 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14390 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
143a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
143b0 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  reed..** If sqli
143c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
143d0 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
143e0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
143f0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
14400 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  freed..**.** The
14410 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
14420 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
14430 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  oc() and sqlite3
14440 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
14450 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
14460 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
14470 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20   byte boundary. 
14480 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
14490 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e  default implemen
144a0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65  tation of the me
144b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
144c0 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a  subsystem uses.*
144d0 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  * the malloc(), 
144e0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
144f0 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79  ee() provided by
14500 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
14510 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37  library..** {H17
14520 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66  382} However, if
14530 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14540 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
14550 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49  SQLITE_MEMORY_SI
14560 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20  ZE=<i>NNN</i> C 
14570 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
14580 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e  ro (where <i>NNN
14590 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  </i>.** is an in
145a0 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c  teger), then SQL
145b0 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61  ite create a sta
145c0 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74 20  tic array of at 
145d0 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c  least.** <i>NNN<
145e0 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  /i> bytes in siz
145f0 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20  e and uses that 
14600 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66  array for all of
14610 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20   its dynamic.** 
14620 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14630 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20  n needs. {END}  
14640 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72  Additional memor
14650 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69  y allocator opti
14660 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64  ons.** may be ad
14670 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
14680 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e  leases..**.** In
14690 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
146a0 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
146b0 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
146c0 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
146d0 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
146e0 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
146f0 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
14700 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
14710 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
14720 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
14730 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
14740 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
14750 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
14760 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
14770 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
14780 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
14790 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
147a0 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   The Windows OS 
147b0 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
147c0 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
147d0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
147e0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
147f0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
14800 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
14810 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
14820 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
14830 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
14840 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
14850 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
14860 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
14870 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
14880 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
14890 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
148a0 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
148b0 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
148c0 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
148d0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
148e0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
148f0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
14900 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
14910 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52  _NOMEM]..**.** R
14920 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
14930 5b 48 31 37 33 30 33 5d 20 5b 48 31 37 33 30 34  [H17303] [H17304
14940 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48 31 37 33  ] [H17305] [H173
14950 30 36 5d 20 5b 48 31 37 33 31 30 5d 20 5b 48 31  06] [H17310] [H1
14960 37 33 31 32 5d 20 5b 48 31 37 33 31 35 5d 20 5b  7312] [H17315] [
14970 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48 31 37 33  H17318].** [H173
14980 32 31 5d 20 5b 48 31 37 33 32 32 5d 20 5b 48 31  21] [H17322] [H1
14990 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7323].**.** The 
149a0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
149b0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
149c0 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
149d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
149e0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
149f0 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
14a00 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
14a10 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
14a20 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
14a30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14a40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
14a50 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
14a60 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
14a70 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
14a80 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
14a90 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
14aa0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
14ab0 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
14ac0 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
14ad0 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
14ae0 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
14af0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
14b00 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
14b10 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
14b20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
14b30 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
14b40 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
14b50 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
14b60 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
14b70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14b80 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
14b90 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 48  or Statistics {H
14ba0 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a  17370} <S30210>.
14bb0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
14bc0 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
14bd0 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
14be0 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
14bf0 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
14c00 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14c10 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
14c20 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
14c30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
14c40 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
14c50 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
14c60 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
14c70 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
14c80 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
14c90 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 37 31 5d  nts:.** [H17371]
14ca0 20 5b 48 31 37 33 37 33 5d 20 5b 48 31 37 33 37   [H17373] [H1737
14cb0 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a 2f 0a 73  4] [H17375].*/.s
14cc0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
14cd0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
14ce0 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
14cf0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
14d00 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
14d10 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
14d20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14d30 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
14d40 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b  mber Generator {
14d50 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e  H17390} <S20000>
14d60 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
14d70 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
14d80 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
14d90 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
14da0 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
14db0 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
14dc0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
14dd0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
14de0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
14df0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
14e00 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
14e10 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
14e20 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
14e30 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
14e40 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
14e50 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
14e60 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
14e70 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
14e80 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
14e90 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
14ea0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
14eb0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
14ec0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
14ed0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  rposes..**.** A 
14ee0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
14ef0 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
14f00 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
14f10 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
14f20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
14f30 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
14f40 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
14f50 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
14f60 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
14f70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
14f80 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
14f90 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
14fa0 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
14fb0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
14fc0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
14fd0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
14fe0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f  fs] object..** O
14ff0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
15000 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
15010 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
15020 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
15030 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
15040 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
15050 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
15060 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
15070 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
15080 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
15090 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39 32 5d 0a  ts:.** [H17392].
150a0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
150b0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
150c0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
150d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
150e0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
150f0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
15100 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 30 31  s {H12500} <S701
15110 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
15120 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
15130 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   a authorizer ca
15140 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
15150 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
15160 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15170 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
15180 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15190 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  t..** The author
151a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
151b0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
151c0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
151d0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
151e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
151f0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
15200 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
15210 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
15220 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
15230 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
15240 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
15250 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f  v2()].  At vario
15260 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
15270 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
15280 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
15290 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
152a0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
152b0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
152c0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
152d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
152e0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
152f0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
15300 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
15310 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72    The authorizer
15320 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
15330 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
15340 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
15350 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
15360 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
15370 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
15380 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
15390 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
153a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
153b0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
153c0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
153d0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
153e0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
153f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
15400 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
15410 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49  ith an error.  I
15420 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
15430 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15440 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
15450 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
15460 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
15470 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
15480 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
15490 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
154a0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
154b0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
154c0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
154d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
154e0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
154f0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
15500 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
15510 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
15520 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
15530 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
15540 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
15550 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e  ted is ok.  When
15560 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
15570 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
15580 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
15590 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
155a0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
155b0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
155c0 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
155d0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
155e0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
155f0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
15600 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
15610 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
15620 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
15630 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
15640 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15650 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
15660 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
15670 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
15680 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
15690 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
156a0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
156b0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
156c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
156d0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
156e0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
156f0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
15700 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
15710 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
15720 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65   authorized. The
15730 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
15740 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
15750 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
15760 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
15770 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
15780 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
15790 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
157a0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
157b0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
157c0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  zed..**.** If th
157d0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
157e0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
157f0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
15800 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
15810 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
15820 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
15830 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
15840 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
15850 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
15860 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
15870 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
15880 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
15890 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
158a0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
158b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
158c0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
158d0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
158e0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
158f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
15900 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
15910 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
15920 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
15930 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
15940 2a 2a 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e  ** If the action
15950 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
15960 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
15970 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15980 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
15990 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
159a0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
159b0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
159c0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
159d0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
159e0 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
159f0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
15a00 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
15a10 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
15a20 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
15a30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15a40 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
15a50 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
15a60 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
15a70 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
15a80 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
15a90 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
15aa0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
15ab0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
15ac0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
15ad0 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
15ae0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
15af0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
15b00 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
15b10 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
15b20 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
15b30 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
15b40 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
15b50 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
15b60 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
15b70 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
15b80 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
15b90 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
15ba0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
15bb0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
15bc0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
15bd0 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
15be0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
15bf0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
15c00 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
15c10 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
15c20 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
15c30 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
15c40 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
15c50 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
15c60 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
15c70 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
15c80 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
15c90 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
15ca0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
15cb0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
15cc0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
15cd0 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
15ce0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
15cf0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
15d00 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
15d10 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
15d20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
15d30 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
15d40 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
15d50 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
15d60 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
15d70 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
15d80 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
15d90 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
15da0 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
15db0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
15dc0 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
15dd0 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
15de0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
15df0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
15e00 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
15e10 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
15e20 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
15e30 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61  ious call.  Disa
15e40 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
15e50 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
15e60 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
15e70 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
15e80 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
15e90 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
15ea0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
15eb0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
15ec0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
15ed0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
15ee0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
15ef0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
15f00 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
15f10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
15f20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
15f30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
15f40 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
15f50 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
15f60 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
15f70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15f80 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
15f90 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
15fa0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
15fb0 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73  h..**.** When [s
15fc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
15fd0 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
15fe0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
15ff0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
16000 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
16010 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
16020 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
16030 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
16040 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
16050 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
16060 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
16070 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
16080 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
16090 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
160a0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
160b0 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
160c0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
160d0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61   Note that the a
160e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
160f0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
16100 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
16110 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
16120 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
16130 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
16140 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
16150 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
16160 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
16170 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
16180 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
16190 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
161a0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
161b0 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
161c0 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
161d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
161e0 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
161f0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
16200 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
16210 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ge..**.** Requir
16220 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35  ements:.** [H125
16230 30 31 5d 20 5b 48 31 32 35 30 32 5d 20 5b 48 31  01] [H12502] [H1
16240 32 35 30 33 5d 20 5b 48 31 32 35 30 34 5d 20 5b  2503] [H12504] [
16250 48 31 32 35 30 35 5d 20 5b 48 31 32 35 30 36 5d  H12505] [H12506]
16260 20 5b 48 31 32 35 30 37 5d 20 5b 48 31 32 35 31   [H12507] [H1251
16270 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31 5d 20 5b  0].** [H12511] [
16280 48 31 32 35 31 32 5d 20 5b 48 31 32 35 32 30 5d  H12512] [H12520]
16290 20 5b 48 31 32 35 32 31 5d 20 5b 48 31 32 35 32   [H12521] [H1252
162a0 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  2].*/.int sqlite
162b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
162c0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
162d0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
162e0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
162f0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
16300 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
16310 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
16320 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
16330 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
16340 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
16350 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20   Codes {H12590} 
16360 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12500>.**.** T
16370 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
16380 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
16390 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
163a0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
163b0 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
163c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
163d0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
163e0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
163f0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
16400 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
16410 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
16420 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
16430 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
16440 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
16450 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
16460 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
16470 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
16480 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
16490 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
164a0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
164b0 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
164c0 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
164d0 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
164e0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
164f0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
16500 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
16510 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
16520 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
16530 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
16540 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
16550 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30   {H12550} <H1250
16560 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
16570 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16580 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
16590 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
165a0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
165b0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
165c0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
165d0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
165e0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
165f0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
16600 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
16610 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
16620 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
16630 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
16640 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
16650 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
16660 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
16670 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
16680 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
16690 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
166a0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
166b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
166c0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
166d0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
166e0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
166f0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
16700 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
16710 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
16720 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
16730 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
16740 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
16750 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
16760 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
16770 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
16780 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
16790 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
167a0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
167b0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
167c0 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
167d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
167e0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
167f0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
16800 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
16810 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
16820 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
16830 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
16840 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16850 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
16860 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
16870 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
16880 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
16890 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
168a0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
168b0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
168c0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
168d0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
168e0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
168f0 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 52 65  L code..**.** Re
16900 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
16910 48 31 32 35 35 31 5d 20 5b 48 31 32 35 35 32 5d  H12551] [H12552]
16920 20 5b 48 31 32 35 35 33 5d 20 5b 48 31 32 35 35   [H12553] [H1255
16930 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  4].*/./*********
16940 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16950 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16960 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
16970 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
16980 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
16990 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
169a0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
169b0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
169c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
169d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
169e0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
169f0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
16a00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
16a10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
16a20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16a30 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
16a40 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
16a50 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
16a60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
16a70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16a80 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
16a90 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
16aa0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
16ab0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
16ac0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ad0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
16ae0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
16af0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
16b00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
16b10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16b20 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
16b30 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
16b40 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
16b50 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
16b60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
16b70 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
16b80 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
16b90 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
16ba0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
16bb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
16bc0 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
16bd0 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
16be0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
16bf0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16c00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
16c10 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
16c20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
16c30 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
16c40 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
16c50 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
16c60 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
16c70 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
16c80 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
16c90 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
16ca0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
16cb0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
16cc0 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
16cd0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
16ce0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
16cf0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
16d00 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
16d10 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
16d20 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
16d30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16d40 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
16d50 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
16d60 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
16d70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
16d80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16d90 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
16da0 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
16db0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
16dc0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
16dd0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16de0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
16df0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
16e00 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
16e10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16e20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16e30 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
16e40 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
16e50 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
16e60 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
16e70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
16e80 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
16e90 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
16ea0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
16eb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
16ec0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16ed0 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
16ee0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
16ef0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
16f00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
16f10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16f20 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
16f30 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
16f40 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
16f50 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
16f60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16f70 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
16f80 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
16f90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
16fa0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
16fb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16fc0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
16fd0 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
16fe0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
16ff0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
17010 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
17020 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
17030 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
17040 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17050 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
17060 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
17070 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
17080 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
17090 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
170a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
170b0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
170c0 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
170d0 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
170e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
170f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
17100 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
17110 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
17120 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
17130 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17140 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
17150 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
17160 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
17170 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
17180 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
17190 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
171a0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
171b0 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
171c0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
171d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
171e0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
171f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
17200 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
17210 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17220 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17230 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
17240 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
17250 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
17260 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
17270 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17280 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
17290 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
172a0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
172b0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
172c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
172d0 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
172e0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
172f0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
17300 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
17310 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17320 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
17330 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
17340 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
17350 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
17360 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17370 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
17380 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
17390 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
173a0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
173b0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
173c0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
173d0 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36  ons {H12280} <S6
173e0 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0400>.** EXPERIM
173f0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
17400 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
17410 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
17420 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
17430 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
17440 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
17450 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
17460 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
17470 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
17480 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
17490 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
174a0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
174b0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
174c0 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
174d0 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
174e0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
174f0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
17500 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61  ep()]..** The ca
17510 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
17520 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
17530 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
17540 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73  ement text.** as
17550 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
17560 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
17570 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  uting.  Addition
17580 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63  al callbacks occ
17590 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
175a0 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
175b0 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
175c0 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
175d0 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
175e0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
175f0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
17600 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
17610 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  igger..**.** The
17620 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
17630 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
17640 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
17650 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
17660 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
17670 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
17680 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61    The profile ca
17690 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
176a0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
176b0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
176c0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
176d0 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
176e0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
176f0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
17700 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  took to run..**.
17710 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
17720 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20 5b 48 31  .** [H12281] [H1
17730 32 32 38 32 5d 20 5b 48 31 32 32 38 33 5d 20 5b  2282] [H12283] [
17740 48 31 32 32 38 34 5d 20 5b 48 31 32 32 38 35 5d  H12284] [H12285]
17750 20 5b 48 31 32 32 38 37 5d 20 5b 48 31 32 32 38   [H12287] [H1228
17760 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a 2a 20 5b  8] [H12289].** [
17770 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51 4c 49 54  H12290].*/.SQLIT
17780 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
17790 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
177a0 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
177b0 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
177c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
177d0 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
177e0 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
177f0 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
17800 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
17810 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
17820 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
17830 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
17840 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
17850 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
17860 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
17870 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30  ks {H12910} <S60
17880 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  400>.**.** This 
17890 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
178a0 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
178b0 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
178c0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
178d0 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
178e0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
178f0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
17900 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
17910 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
17920 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
17930 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
17940 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
17950 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
17960 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
17970 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
17980 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
17990 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
179a0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  query..**.** If 
179b0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
179c0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
179d0 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
179e0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
179f0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
17a00 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
17a10 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
17a20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
17a30 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
17a40 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
17a50 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
17a60 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75  gress handler mu
17a70 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
17a80 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
17a90 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
17aa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
17ab0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
17ac0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
17ad0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
17ae0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17af0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
17b00 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
17b10 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
17b20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17b30 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
17b40 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
17b50 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
17b60 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ph..**.** Requir
17b70 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39  ements:.** [H129
17b80 31 31 5d 20 5b 48 31 32 39 31 32 5d 20 5b 48 31  11] [H12912] [H1
17b90 32 39 31 33 5d 20 5b 48 31 32 39 31 34 5d 20 5b  2913] [H12914] [
17ba0 48 31 32 39 31 35 5d 20 5b 48 31 32 39 31 36 5d  H12915] [H12916]
17bb0 20 5b 48 31 32 39 31 37 5d 20 5b 48 31 32 39 31   [H12917] [H1291
17bc0 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  8].**.*/.void sq
17bd0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
17be0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
17bf0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
17c00 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
17c10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
17c20 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
17c30 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
17c40 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30  {H12700} <S40200
17c50 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
17c60 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
17c70 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
17c80 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
17c90 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
17ca0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
17cb0 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
17cc0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
17cd0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
17ce0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
17cf0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
17d00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
17d10 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
17d20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
17d30 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
17d40 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
17d50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17d60 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
17d70 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
17d80 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
17d90 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
17da0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
17db0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
17dc0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
17dd0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
17de0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
17df0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
17e00 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
17e10 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
17e20 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
17e30 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
17e40 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
17e50 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
17e60 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
17e70 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
17e80 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
17e90 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
17ea0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
17eb0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
17ec0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
17ed0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
17ee0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
17ef0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
17f00 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
17f10 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
17f20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
17f30 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
17f40 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
17f50 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
17f60 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
17f70 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
17f80 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
17f90 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
17fa0 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
17fb0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
17fc0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
17fd0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
17fe0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
17ff0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
18000 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
18010 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
18020 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
18030 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
18040 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
18050 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
18060 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
18070 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
18080 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
18090 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
180a0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
180b0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
180c0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
180d0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
180e0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
180f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
18100 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
18110 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
18120 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
18130 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
18140 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
18150 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
18160 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
18170 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
18180 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
18190 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
181a0 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
181b0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
181c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
181d0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
181e0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
181f0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
18200 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
18210 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
18220 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
18230 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
18240 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ACHE],.** and/or
18250 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
18260 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
18270 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  s:.**.** <dl>.**
18280 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
18290 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
182a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
182b0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
182c0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
182d0 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
182e0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
182f0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
18300 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
18310 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
18320 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
18330 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
18340 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
18350 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
18360 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
18370 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
18380 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
18390 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
183a0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
183b0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
183c0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
183d0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
183e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
183f0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
18400 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
18410 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
18420 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
18430 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
18440 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
18450 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
18460 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
18470 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
18480 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
18490 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
184a0 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66  is creates it if
184b0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
184c0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
184d0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
184e0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
184f0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
18500 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
18510 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
18520 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ().</dd>.** </dl
18530 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
18540 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
18550 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
18560 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
18570 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
18580 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
18590 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  or one of the co
185a0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
185b0 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a   above combined.
185c0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
185d0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
185e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
185f0 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b  FULLMUTEX],.** [
18600 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
18610 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20  EDCACHE] and/or 
18620 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
18630 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c  REDCACHE] flags,
18640 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
18650 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
18660 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
18670 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
18680 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
18690 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
186a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
186b0 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
186c0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
186d0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
186e0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
186f0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
18700 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
18710 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
18720 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
18730 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b  me.  If the.** [
18740 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
18750 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
18760 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
18770 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18780 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
18790 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
187a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
187b0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
187c0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
187d0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
187e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
187f0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 54 68  tart-time..** Th
18800 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
18810 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
18820 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
18830 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18840 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
18850 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
18860 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
18870 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
18880 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
18890 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
188a0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
188b0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
188c0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 54 68  ed_cache()].  Th
188d0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
188e0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
188f0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
18900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18910 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
18920 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
18930 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
18940 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
18950 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  nabled..**.** If
18960 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
18970 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
18980 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
18990 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
189a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
189b0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
189c0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69  connection.  Thi
189d0 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
189e0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
189f0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
18a00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18a10 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
18a20 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
18a30 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
18a40 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
18a50 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
18a60 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
18a70 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
18a80 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
18a90 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
18aa0 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
18ab0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
18ac0 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
18ad0 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
18ae0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
18af0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
18b00 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
18b10 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
18b20 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
18b30 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
18b40 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
18b50 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
18b60 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
18b70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
18b80 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
18b90 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
18ba0 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69  eated.  This pri
18bb0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
18bc0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
18bd0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
18be0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
18bf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18c00 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
18c10 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
18c20 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
18c30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
18c40 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
18c50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
18c60 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
18c70 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
18c80 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
18c90 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
18ca0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
18cb0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
18cc0 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72  se.  If the four
18cd0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
18ce0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
18cf0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
18d00 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
18d10 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
18d20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
18d30 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
18d40 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
18d50 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
18d60 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
18d70 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
18d80 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
18d90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
18da0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
18db0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
18dc0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
18dd0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
18de0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
18df0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
18e00 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
18e10 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
18e20 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
18e30 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
18e40 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
18e50 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
18e60 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
18e70 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
18e80 2a 20 5b 48 31 32 37 30 31 5d 20 5b 48 31 32 37  * [H12701] [H127
18e90 30 32 5d 20 5b 48 31 32 37 30 33 5d 20 5b 48 31  02] [H12703] [H1
18ea0 32 37 30 34 5d 20 5b 48 31 32 37 30 36 5d 20 5b  2704] [H12706] [
18eb0 48 31 32 37 30 37 5d 20 5b 48 31 32 37 30 39 5d  H12707] [H12709]
18ec0 20 5b 48 31 32 37 31 31 5d 0a 2a 2a 20 5b 48 31   [H12711].** [H1
18ed0 32 37 31 32 5d 20 5b 48 31 32 37 31 33 5d 20 5b  2712] [H12713] [
18ee0 48 31 32 37 31 34 5d 20 5b 48 31 32 37 31 37 5d  H12714] [H12717]
18ef0 20 5b 48 31 32 37 31 39 5d 20 5b 48 31 32 37 32   [H12719] [H1272
18f00 31 5d 20 5b 48 31 32 37 32 33 5d 0a 2a 2f 0a 69  1] [H12723].*/.i
18f10 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
18f20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
18f30 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
18f40 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
18f50 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
18f60 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
18f70 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
18f80 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
18f90 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
18fa0 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
18fb0 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
18fc0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
18fd0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
18fe0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
18ff0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
19000 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
19010 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
19020 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19030 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
19040 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
19050 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
19060 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
19070 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
19080 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
19090 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
190a0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
190b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
190c0 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
190d0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
190e0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
190f0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
19100 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
19110 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
19120 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48   And Messages {H
19130 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a  12800} <S60200>.
19140 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
19150 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
19160 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
19170 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
19180 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
19190 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
191a0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
191b0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
191c0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
191d0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
191e0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
191f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
19200 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
19210 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
19220 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
19230 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
19240 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
19250 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
19260 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
19270 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54  is undefined.  T
19280 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
19290 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
192a0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
192b0 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
192c0 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
192d0 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
192e0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
192f0 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
19300 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
19310 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
19320 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
19330 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
19340 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
19350 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
19360 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
19370 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
19380 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
19390 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
193a0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
193b0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
193c0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
193d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
193e0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
193f0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
19400 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
19410 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
19420 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
19430 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
19440 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
19450 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
19460 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
19470 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
19480 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
19490 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
194a0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
194b0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
194c0 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
194d0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
194e0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
194f0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
19500 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
19510 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
19520 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
19530 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
19540 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
19550 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
19560 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
19570 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
19580 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
19590 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
195a0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
195b0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
195c0 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
195d0 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
195e0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
195f0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
19600 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
19610 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
19620 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
19630 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
19640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19650 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
19660 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
19670 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
19680 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
19690 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
196a0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
196b0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
196c0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
196d0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
196e0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
196f0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
19700 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
19710 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
19720 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
19730 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
19740 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
19750 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
19760 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
19770 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
19780 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
19790 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
197a0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
197b0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
197c0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
197d0 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
197e0 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  et..**.** Requir
197f0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 38  ements:.** [H128
19800 30 31 5d 20 5b 48 31 32 38 30 32 5d 20 5b 48 31  01] [H12802] [H1
19810 32 38 30 33 5d 20 5b 48 31 32 38 30 37 5d 20 5b  2803] [H12807] [
19820 48 31 32 38 30 38 5d 20 5b 48 31 32 38 30 39 5d  H12808] [H12809]
19830 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
19840 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
19850 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
19860 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
19870 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
19880 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
19890 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
198a0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
198b0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
198c0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
198d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
198e0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
198f0 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48  ject {H13000} <H
19900 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  13010>.** KEYWOR
19910 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
19920 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
19930 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
19940 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
19950 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
19960 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
19970 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
19980 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
19990 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
199a0 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
199b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
199c0 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
199d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
199e0 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
199f0 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
19a00 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
19a10 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
19a20 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
19a30 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
19a40 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
19a50 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
19a60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
19a70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
19a80 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
19a90 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
19aa0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
19ab0 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
19ac0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
19ad0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
19ae0 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
19af0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
19b00 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
19b10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
19b20 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
19b30 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
19b40 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
19b50 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
19b60 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
19b70 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
19b80 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
19b90 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
19ba0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
19bb0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
19bc0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
19bd0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
19be0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
19bf0 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
19c00 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
19c10 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
19c20 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
19c30 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
19c40 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
19c50 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
19c60 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
19c70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
19c80 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48  n-time Limits {H
19c90 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a  12760} <S20600>.
19ca0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
19cb0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
19cc0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
19cd0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
19ce0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
19cf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
19d00 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
19d10 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
19d20 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
19d30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19d40 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
19d50 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
19d60 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
19d70 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
19d80 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
19d90 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
19da0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
19db0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
19dc0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
19dd0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
19de0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
19df0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
19e00 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
19e10 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20  construct.  The 
19e20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
19e30 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a   the old limit..
19e40 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77  **.** If the new
19e50 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
19e60 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
19e70 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
19e80 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ged..** For the 
19e90 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f  limit category o
19ea0 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58  f SQLITE_LIMIT_X
19eb0 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  YZ there is a .*
19ec0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
19ed0 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
19ee0 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c   set by a compil
19ef0 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63  e-time C preproc
19f00 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65  essor macro name
19f10 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  d .** [limits | 
19f20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e  SQLITE_MAX_XYZ].
19f30 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
19f40 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
19f50 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
19f60 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70  AX_".).** Attemp
19f70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
19f80 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
19f90 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
19fa0 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
19fb0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
19fc0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69  he hard upper li
19fd0 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74  mit..**.** Run t
19fe0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
19ff0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
1a000 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
1a010 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
1a020 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
1a030 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
1a040 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
1a050 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
1a060 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
1a070 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
1a080 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
1a090 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
1a0a0 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
1a0b0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
1a0c0 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
1a0d0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
1a0e0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
1a0f0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
1a100 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
1a110 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
1a120 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
1a130 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
1a140 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
1a150 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1a160 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
1a170 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
1a180 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
1a190 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
1a1a0 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
1a1b0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
1a1c0 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
1a1d0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
1a1e0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
1a1f0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
1a200 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
1a210 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
1a220 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
1a230 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1a240 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
1a250 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
1a260 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
1a270 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
1a280 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
1a290 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
1a2a0 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
1a2b0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
1a2c0 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
1a2d0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
1a2e0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
1a2f0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
1a300 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
1a310 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
1a320 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
1a330 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ases..**.** Requ
1a340 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1a350 32 37 36 32 5d 20 5b 48 31 32 37 36 36 5d 20 5b  2762] [H12766] [
1a360 48 31 32 37 36 39 5d 0a 2a 2f 0a 69 6e 74 20 73  H12769].*/.int s
1a370 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
1a380 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
1a390 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
1a3a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1a3b0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
1a3c0 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20  gories {H12790} 
1a3d0 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57  <H12760>.** KEYW
1a3e0 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
1a3f0 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
1a400 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
1a410 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1a420 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
1a430 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
1a440 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
1a450 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
1a460 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
1a470 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
1a480 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
1a490 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
1a4a0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
1a4b0 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
1a4c0 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
1a4d0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
1a4e0 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
1a4f0 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
1a500 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
1a510 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
1a520 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
1a530 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1a540 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
1a550 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
1a560 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
1a570 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  w.<dd>.**.** <dt
1a580 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
1a590 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
1a5a0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1a5b0 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
1a5c0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
1a5d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1a5e0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
1a5f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a600 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1a610 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
1a620 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
1a630 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
1a640 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
1a650 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
1a660 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1a670 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1a680 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
1a690 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
1a6a0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
1a6b0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1a6c0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1a6d0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1a6e0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
1a6f0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
1a700 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
1a710 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  sion.</dd>.**.**
1a720 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1a730 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1a740 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1a750 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1a760 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1a770 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1a780 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1a790 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a7a0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
1a7b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1a7c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1a7d0 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
1a7e0 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
1a7f0 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
1a800 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1a810 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1a820 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1a830 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1a840 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
1a850 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1a860 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
1a870 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
1a880 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
1a890 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1a8a0 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
1a8b0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1a8c0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
1a8d0 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
1a8e0 61 74 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a  atabases].</dd>.
1a8f0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a900 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1a910 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
1a920 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1a930 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
1a940 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
1a950 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
1a960 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
1a970 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  rators.</dd>.**.
1a980 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1a990 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1a9a0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
1a9b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1a9c0 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20  er of variables 
1a9d0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1a9e0 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20  ent that can.** 
1a9f0 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a  be bound.</dd>.*
1aa00 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1aa10 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
1aa20 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1aa30 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1aa40 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
1aa50 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
1aa60 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  >.** </dl>.*/.#d
1aa70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1aa80 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
1aa90 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
1aaa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1aab0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
1aac0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
1aad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1aae0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
1aaf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1ab00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ab10 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1ab20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ab30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
1ab40 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1ab50 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1ab60 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
1ab70 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
1ab80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ab90 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
1aba0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
1abb0 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
1abc0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
1abd0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1abe0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
1abf0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
1ac00 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
1ac10 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
1ac20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
1ac30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
1ac40 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
1ac50 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
1ac60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
1ac70 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
1ac80 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20        10../*.** 
1ac90 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1aca0 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
1acb0 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53  ment {H13010} <S
1acc0 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10000>.** KEYWOR
1acd0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
1ace0 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
1acf0 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
1ad00 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
1ad10 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
1ad20 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
1ad30 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
1ad40 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
1ad50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
1ad60 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
1ad70 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
1ad80 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
1ad90 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
1ada0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
1adb0 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
1adc0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
1add0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1ade0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
1adf0 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
1ae00 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
1ae10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
1ae20 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
1ae30 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
1ae40 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1ae50 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
1ae60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
1ae70 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
1ae80 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
1ae90 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1aea0 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
1aeb0 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
1aec0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1aed0 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
1aee0 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
1aef0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1af00 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
1af10 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
1af20 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
1af30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74  *.** If the nByt
1af40 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
1af50 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
1af60 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
1af70 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
1af80 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1af90 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20  or. If nByte is 
1afa0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1afb0 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
1afc0 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
1afd0 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
1afe0 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e  om zSql.  When n
1aff0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1b000 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
1b010 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
1b020 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
1b030 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
1b040 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
1b050 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
1b060 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
1b070 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
1b080 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
1b090 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
1b0a0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
1b0b0 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
1b0c0 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
1b0d0 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
1b0e0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
1b0f0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
1b100 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
1b110 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1b120 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
1b130 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1b140 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
1b150 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
1b160 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
1b170 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
1b180 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 70  ytes..**.** If p
1b190 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
1b1a0 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
1b1b0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1b1c0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
1b1d0 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
1b1e0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
1b1f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1b200 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
1b210 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
1b220 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
1b230 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1b240 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
1b250 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1b260 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
1b270 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
1b280 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c  .** *ppStmt is l
1b290 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
1b2a0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
1b2b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1b2c0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
1b2d0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
1b2e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
1b2f0 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   If there is an 
1b300 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
1b310 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
1b320 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20  .  If the input 
1b330 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
1b340 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
1b350 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
1b360 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
1b370 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
1b380 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
1b390 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
1b3a0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
1b3b0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
1b3c0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
1b3d0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
1b3e0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
1b3f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1b400 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
1b410 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1b420 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
1b430 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
1b440 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  * On success, [S
1b450 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1b460 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65  urned, otherwise
1b470 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1b480 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1b490 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1b4a0 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
1b4b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1b4c0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
1b4d0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
1b4e0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
1b4f0 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
1b500 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
1b510 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
1b520 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
1b530 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1b540 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
1b550 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
1b560 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69  ** In the "v2" i
1b570 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
1b580 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1b590 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
1b5a0 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
1b5b0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
1b5c0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
1b5d0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
1b5e0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
1b5f0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
1b600 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b610 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
1b620 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
1b630 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
1b640 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
1b650 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64  <li>.** If the d
1b660 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
1b670 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
1b680 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
1b690 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
1b6a0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
1b6b0 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
1b6c0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
1b6d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
1b6e0 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
1b6f0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
1b700 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
1b710 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68  ain.  If the sch
1b720 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20  ema has changed 
1b730 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74  in.** a way that
1b740 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65   makes the state
1b750 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76  ment no longer v
1b760 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  alid, [sqlite3_s
1b770 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c  tep()] will stil
1b780 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
1b790 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75  ITE_SCHEMA].  Bu
1b7a0 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67  t unlike the leg
1b7b0 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53  acy behavior, [S
1b7c0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73  QLITE_SCHEMA] is
1b7d0 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20  .** now a fatal 
1b7e0 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20  error.  Calling 
1b7f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1b800 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c  _v2()] again wil
1b810 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a  l not make the.*
1b820 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e  * error go away.
1b830 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c    Note: use [sql
1b840 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74  ite3_errmsg()] t
1b850 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a  o find the text.
1b860 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e  ** of the parsin
1b870 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73  g error that res
1b880 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49  ults in an [SQLI
1b890 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72  TE_SCHEMA] retur
1b8a0 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
1b8b0 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61  * <li>.** When a
1b8c0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
1b8d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b8e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
1b8f0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
1b900 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
1b910 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
1b920 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68  rror codes].  Th
1b930 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1b940 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
1b950 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1b960 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
1b970 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
1b980 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
1b990 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75   code.** and you
1b9a0 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
1b9b0 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
1b9c0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
1b9d0 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a  set()] in order.
1b9e0 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  ** to find the u
1b9f0 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
1ba00 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
1ba10 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
1ba20 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
1ba30 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
1ba40 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
1ba50 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
1ba60 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
1ba70 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1ba80 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
1ba90 20 76 61 6c 75 65 20 6f 66 20 61 20 5b 70 61 72   value of a [par
1baa0 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61  ameter | host pa
1bab0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
1bac0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
1bad0 68 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ht.** change the
1bae0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
1baf0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1bb00 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
1bb10 6d 61 79 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  may be.** automa
1bb20 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
1bb30 65 64 20 28 61 73 20 69 66 20 74 68 65 72 65 20  ed (as if there 
1bb40 68 61 64 20 62 65 65 6e 20 61 20 73 63 68 65 6d  had been a schem
1bb50 61 20 63 68 61 6e 67 65 29 20 6f 6e 20 74 68 65  a change) on the
1bb60 20 66 69 72 73 74 20 0a 2a 2a 20 5b 73 71 6c 69   first .** [sqli
1bb70 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
1bb80 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63   following any c
1bb90 68 61 6e 67 65 20 74 6f 20 74 68 65 20 0a 2a 2a  hange to the .**
1bba0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1bbb0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
1bbc0 6f 66 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  of the [paramete
1bbd0 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  r]. .** </li>.**
1bbe0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 71   </ol>.**.** Req
1bbf0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1bc00 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32 5d 20  13011] [H13012] 
1bc10 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30 31 34  [H13013] [H13014
1bc20 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31 33 30  ] [H13015] [H130
1bc30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b 48 31  16] [H13019] [H1
1bc40 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20  3021].**.*/.int 
1bc50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1bc60 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1bc70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1bc80 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1bc90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1bca0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1bcb0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1bcc0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1bcd0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1bce0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1bcf0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1bd00 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1bd10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1bd20 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1bd30 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1bd40 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1bd50 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1bd60 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1bd70 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1bd80 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1bd90 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1bda0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
1bdb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1bdc0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1bdd0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1bde0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1bdf0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1be00 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1be10 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1be20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1be30 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1be40 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1be50 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1be60 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1be70 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1be80 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1be90 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1bea0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1beb0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1bec0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1bed0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1bee0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
1bef0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1bf00 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1bf10 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1bf20 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1bf30 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1bf40 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1bf50 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1bf60 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1bf70 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1bf80 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1bf90 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1bfa0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1bfb0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1bfc0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1bfd0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1bfe0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1bff0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1c000 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1c010 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1c020 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1c030 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1c040 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1c050 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1c060 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1c070 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1c080 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1c090 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1c0a0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1c0b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1c0c0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1c0d0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1c0e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1c0f0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1c100 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1c110 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1c120 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1c130 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1c140 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1c150 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1c160 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1c170 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1c180 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48  Statement SQL {H
1c190 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a  13100} <H13000>.
1c1a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1c1b0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1c1c0 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
1c1d0 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
1c1e0 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
1c1f0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
1c200 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
1c210 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
1c220 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
1c230 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
1c240 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1c250 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1c260 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1c270 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1c280 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
1c290 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d 20 5b  s:.** [H13101] [
1c2a0 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30 33 5d  H13102] [H13103]
1c2b0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1c2c0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1c2d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1c2e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c2f0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1c300 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1c310 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32  t {H15000} <S202
1c320 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1c330 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1c340 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1c350 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1c360 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1c370 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1c380 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1c390 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1c3a0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1c3b0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1c3c0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1c3d0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
1c3e0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
1c3f0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
1c400 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c  s it stores. Val
1c410 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
1c420 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1c430 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
1c440 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1c450 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1c460 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1c470 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1c480 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1c490 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1c4a0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1c4b0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1c4c0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1c4d0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1c4e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1c4f0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1c500 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1c510 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1c520 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1c530 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1c540 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1c550 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1c560 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1c570 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1c580 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
1c590 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
1c5a0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
1c5b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1c5c0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
1c5d0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
1c5e0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
1c5f0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
1c600 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
1c610 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
1c620 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
1c630 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1c640 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
1c650 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1c660 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
1c670 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
1c680 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1c690 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1c6a0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
1c6b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
1c6c0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
1c6d0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
1c6e0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
1c6f0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
1c700 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
1c710 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
1c720 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
1c730 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
1c740 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
1c750 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
1c760 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1c770 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1c780 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
1c790 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
1c7a0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1c7b0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
1c7c0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1c7d0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1c7e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1c7f0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
1c800 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
1c810 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
1c820 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1c830 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1c840 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1c850 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1c860 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
1c870 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1c880 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
1c890 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1c8a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1c8b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1c8c0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
1c8d0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
1c8e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1c8f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1c900 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
1c910 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
1c920 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
1c930 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c940 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1c950 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1c960 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
1c970 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
1c980 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
1c990 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
1c9a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
1c9b0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
1c9c0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
1c9d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1c9e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
1c9f0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
1ca00 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
1ca10 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
1ca20 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1ca30 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
1ca40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1ca50 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1ca60 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1ca70 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1ca80 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1ca90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1caa0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1cab0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1cac0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1cad0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1cae0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
1caf0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
1cb00 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30  {H16001} <S20200
1cb10 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  >.**.** The cont
1cb20 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
1cb30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
1cb40 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
1cb50 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
1cb60 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
1cb70 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    A pointer to a
1cb80 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
1cb90 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
1cba0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
1cbb0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
1cbc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1cbd0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
1cbe0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1cbf0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1cc00 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
1cc10 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
1cc20 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
1cc30 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
1cc40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
1cc50 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
1cc60 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
1cc70 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
1cc80 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
1cc90 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
1cca0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
1ccb0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
1ccc0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
1ccd0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
1cce0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
1ccf0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
1cd00 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
1cd10 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
1cd20 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
1cd30 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
1cd40 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
1cd50 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
1cd60 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
1cd70 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13500} <S70300>
1cd80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
1cd90 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
1cda0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
1cdb0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1cdc0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
1cdd0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
1cde0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
1cdf0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
1ce00 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49  binding}.**.** I
1ce10 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
1ce20 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
1ce30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ce40 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1ce50 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
1ce60 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
1ce70 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
1ce80 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
1ce90 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
1cea0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
1ceb0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1cec0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
1ced0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
1cee0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
1cef0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
1cf00 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
1cf10 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
1cf20 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
1cf30 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
1cf40 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
1cf50 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
1cf60 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
1cf70 69 66 65 72 2e 20 20 54 68 65 20 76 61 6c 75 65  ifer.  The value
1cf80 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
1cf90 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
1cfa0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
1cfb0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
1cfc0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
1cfd0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
1cfe0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
1cff0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
1d000 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
1d010 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
1d020 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1d030 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1d040 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
1d050 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
1d060 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1d070 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
1d080 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
1d090 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d0a0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
1d0b0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  ariants..**.** T
1d0c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1d0d0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
1d0e0 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
1d0f0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
1d100 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  ** The leftmost 
1d110 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
1d120 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
1d130 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20    When the same 
1d140 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
1d150 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
1d160 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
1d170 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
1d180 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
1d190 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
1d1a0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
1d1b0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
1d1c0 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f  .** The index fo
1d1d0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
1d1e0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
1d1f0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
1d200 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1d210 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1d220 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
1d230 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20  .  The index.** 
1d240 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
1d250 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
1d260 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68  ue of NNN..** Th
1d270 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
1d280 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
1d290 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
1d2a0 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
1d2b0 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
1d2c0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1d2d0 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
1d2e0 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
1d2f0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
1d300 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
1d310 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
1d320 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1d330 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
1d340 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
1d350 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
1d360 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
1d370 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
1d380 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
1d390 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
1d3a0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
1d3b0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
1d3c0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
1d3d0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
1d3e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1d3f0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20  aracters..** If 
1d400 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1d410 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
1d420 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
1d430 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
1d440 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1d450 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
1d460 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1d470 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ator..**.** The 
1d480 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
1d490 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
1d4a0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
1d4b0 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
1d4c0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
1d4d0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
1d4e0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
1d4f0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
1d500 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
1d510 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
1d520 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1d530 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74   it. If the fift
1d540 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
1d550 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
1d560 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
1d570 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
1d580 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
1d590 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
1d5a0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
1d5b0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
1d5c0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
1d5d0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
1d5e0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
1d5f0 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
1d600 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
1d610 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
1d620 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
1d630 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
1d640 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
1d650 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
1d660 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
1d670 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
1d680 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
1d690 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
1d6a0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
1d6b0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
1d6c0 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
1d6d0 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
1d6e0 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20  with zeroes.  A 
1d6f0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
1d700 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
1d710 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
1d720 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
1d730 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
1d740 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
1d750 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
1d760 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
1d770 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
1d780 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
1d790 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
1d7a0 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
1d7b0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
1d7c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
1d7d0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
1d7e0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
1d7f0 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61  tines..** A nega
1d800 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
1d810 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
1d820 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
1d830 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
1d840 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
1d850 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d  d_*() routines m
1d860 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66  ust be called af
1d870 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ter.** [sqlite3_
1d880 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61  prepare_v2()] (a
1d890 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  nd its variants)
1d8a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
1d8b0 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66  et()] and.** bef
1d8c0 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ore [sqlite3_ste
1d8d0 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67  p()]..** Binding
1d8e0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
1d8f0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1d900 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
1d910 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70  ne..** Unbound p
1d920 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
1d930 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
1d940 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  L..**.** These r
1d950 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1d960 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
1d970 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f  ccess or an erro
1d980 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79  r code if.** any
1d990 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
1d9a0 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  .  [SQLITE_RANGE
1d9b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1d9c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
1d9d0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
1d9e0 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54  f range.  [SQLIT
1d9f0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
1da00 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
1da10 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49   fails..** [SQLI
1da20 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74  TE_MISUSE] might
1da30 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
1da40 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
1da50 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a  re called on a.*
1da60 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  * virtual machin
1da70 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72  e that is the wr
1da80 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69  ong state or whi
1da90 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62  ch has already b
1daa0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a  een finalized..*
1dab0 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d  * Detection of m
1dac0 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61  isuse is unrelia
1dad0 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ble.  Applicatio
1dae0 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65  ns should not de
1daf0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54  pend.** on SQLIT
1db00 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73  E_MISUSE returns
1db10 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  .  SQLITE_MISUSE
1db20 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
1db30 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20  indicate a.** a 
1db40 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74  logic error in t
1db50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1db60 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1db70 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1db80 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72  .** panic rather
1db90 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c   than return SQL
1dba0 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a  ITE_MISUSE..**.*
1dbb0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1dbc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1dbd0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
1dbe0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1dbf0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
1dc00 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
1dc10 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1dc20 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  dex()]..**.** Re
1dc30 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1dc40 48 31 33 35 30 36 5d 20 5b 48 31 33 35 30 39 5d  H13506] [H13509]
1dc50 20 5b 48 31 33 35 31 32 5d 20 5b 48 31 33 35 31   [H13512] [H1351
1dc60 35 5d 20 5b 48 31 33 35 31 38 5d 20 5b 48 31 33  5] [H13518] [H13
1dc70 35 32 31 5d 20 5b 48 31 33 35 32 34 5d 20 5b 48  521] [H13524] [H
1dc80 31 33 35 32 37 5d 0a 2a 2a 20 5b 48 31 33 35 33  13527].** [H1353
1dc90 30 5d 20 5b 48 31 33 35 33 33 5d 20 5b 48 31 33  0] [H13533] [H13
1dca0 35 33 36 5d 20 5b 48 31 33 35 33 39 5d 20 5b 48  536] [H13539] [H
1dcb0 31 33 35 34 32 5d 20 5b 48 31 33 35 34 35 5d 20  13542] [H13545] 
1dcc0 5b 48 31 33 35 34 38 5d 20 5b 48 31 33 35 35 31  [H13548] [H13551
1dcd0 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ].**.*/.int sqli
1dce0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
1dcf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1dd00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1dd10 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
1dd20 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
1dd30 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
1dd40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1dd50 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
1dd60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
1dd70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1dd80 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
1dd90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
1dda0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
1ddb0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
1ddc0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
1ddd0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
1dde0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
1ddf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1de00 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
1de10 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1de20 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
1de30 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1de40 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1de50 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
1de60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1de70 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
1de80 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
1de90 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1dea0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
1deb0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1dec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
1ded0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1dee0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
1def0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
1df00 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
1df10 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
1df20 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
1df30 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30   {H13600} <S7030
1df40 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
1df50 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
1df60 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
1df70 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
1df80 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
1df90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1dfa0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
1dfb0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
1dfc0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
1dfd0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
1dfe0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
1dff0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
1e000 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
1e010 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
1e020 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
1e030 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
1e040 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
1e050 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
1e060 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
1e070 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  * This routine a
1e080 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
1e090 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1e0a0 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
1e0b0 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
1e0c0 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
1e0d0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
1e0e0 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
1e0f0 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
1e100 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
1e110 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
1e120 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
1e130 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a  ?NNN are used,.*
1e140 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
1e150 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
1e160 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1e170 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1e180 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1e190 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1e1a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1e1b0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
1e1c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1e1d0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1e1e0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1e1f0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 30 31  ents:.** [H13601
1e200 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1e210 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1e220 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
1e230 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
1e240 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
1e250 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20   Host Parameter 
1e260 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30  {H13620} <S70300
1e270 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
1e280 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1e290 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61  ointer to the na
1e2a0 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a  me of the n-th.*
1e2b0 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  * [SQL parameter
1e2c0 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] in a [prepared
1e2d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
1e2e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
1e2f0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
1e300 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
1e310 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
1e320 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
1e330 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
1e340 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
1e350 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1e360 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
1e370 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
1e380 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
1e390 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
1e3a0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
1e3b0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
1e3c0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
1e3d0 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65  ame..** Paramete
1e3e0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
1e3f0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
1e400 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
1e410 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
1e420 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65  nd are also refe
1e430 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e  rred to as "anon
1e440 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
1e450 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  "..**.** The fir
1e460 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
1e470 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
1e480 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
1e490 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e  * If the value n
1e4a0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1e4b0 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20   or if the n-th 
1e4c0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1e4d0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
1e4e0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
1e4f0 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73    The returned s
1e500 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
1e510 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
1e520 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
1e530 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
1e540 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
1e550 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
1e560 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
1e570 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1e580 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
1e590 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1e5a0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1e5b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1e5c0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
1e5d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1e5e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1e5f0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
1e600 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1e610 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1e620 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1e630 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 32 31  ents:.** [H13621
1e640 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ].*/.const char 
1e650 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
1e660 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
1e670 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
1e680 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e690 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
1e6a0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
1e6b0 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34  iven Name {H1364
1e6c0 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
1e6d0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64  * Return the ind
1e6e0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
1e6f0 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
1e700 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69   name.  The.** i
1e710 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
1e720 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
1e730 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
1e740 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
1e750 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
1e760 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
1e770 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72  _bind()].  A zer
1e780 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
1e790 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
1e7a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
1e7b0 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74  nd.  The paramet
1e7c0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
1e7d0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
1e7e0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
1e7f0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1e800 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
1e810 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
1e820 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1e830 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1e840 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1e850 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1e860 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1e870 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1e880 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1e890 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
1e8a0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1e8b0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1e8c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
1e8d0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36  ements:.** [H136
1e8e0 34 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  41].*/.int sqlit
1e8f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1e900 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
1e910 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
1e920 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
1e930 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
1e940 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
1e950 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
1e960 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20  tement {H13660} 
1e970 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43  <S70300>.**.** C
1e980 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
1e990 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
1e9a0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
1e9b0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
1e9c0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
1e9d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
1e9e0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
1e9f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ea00 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20  t]..** Use this 
1ea10 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
1ea20 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
1ea30 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ters to NULL..**
1ea40 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1ea50 3a 0a 2a 2a 20 5b 48 31 33 36 36 31 5d 0a 2a 2f  :.** [H13661].*/
1ea60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
1ea70 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
1ea80 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1ea90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
1eaa0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
1eab0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
1eac0 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e  H13710} <S10700>
1ead0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
1eae0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1eaf0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
1eb00 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
1eb10 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
1eb20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54  ed statement]. T
1eb30 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
1eb40 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
1eb50 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
1eb60 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
1eb70 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
1eb80 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
1eb90 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
1eba0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1ebb0 2a 20 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a 69 6e  * [H13711].*/.in
1ebc0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
1ebd0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
1ebe0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
1ebf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1ec00 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
1ec10 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37  Result Set {H137
1ec20 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  20} <S10700>.**.
1ec30 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1ec40 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
1ec50 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
1ec60 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
1ec70 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
1ec80 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
1ec90 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
1eca0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
1ecb0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
1ecc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1ecd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
1ece0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1ecf0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
1ed00 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
1ed10 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
1ed20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1ed30 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1ed40 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1ed50 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ng.  The first p
1ed60 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
1ed70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ed80 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
1ed90 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
1eda0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
1edb0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1edc0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
1edd0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54  olumn number.  T
1ede0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
1edf0 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
1ee00 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  **.** The return
1ee10 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
1ee20 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
1ee30 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
1ee40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1ee50 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
1ee60 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
1ee70 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
1ee80 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
1ee90 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
1eea0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
1eeb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1eec0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
1eed0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
1eee0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
1eef0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
1ef00 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
1ef10 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
1ef20 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
1ef30 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
1ef40 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
1ef50 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
1ef60 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1ef70 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
1ef80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
1ef90 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
1efa0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
1efb0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
1efc0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
1efd0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
1efe0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
1eff0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
1f000 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
1f010 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
1f020 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
1f030 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
1f040 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
1f050 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
1f060 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
1f070 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  t..**.** Require
1f080 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 32  ments:.** [H1372
1f090 31 5d 20 5b 48 31 33 37 32 33 5d 20 5b 48 31 33  1] [H13723] [H13
1f0a0 37 32 34 5d 20 5b 48 31 33 37 32 35 5d 20 5b 48  724] [H13725] [H
1f0b0 31 33 37 32 36 5d 20 5b 48 31 33 37 32 37 5d 0a  13726] [H13727].
1f0c0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1f0d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1f0e0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1f0f0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
1f100 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1f110 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
1f120 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
1f130 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f140 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
1f150 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
1f160 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53  sult {H13740} <S
1f170 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
1f180 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
1f190 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
1f1a0 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f  etermine what co
1f1b0 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20  lumn of what.** 
1f1c0 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64  table in which d
1f1d0 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74  atabase a result
1f1e0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
1f1f0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66  tatement comes f
1f200 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  rom..** The name
1f210 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1f220 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
1f230 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
1f240 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
1f250 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
1f260 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
1f270 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
1f280 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
1f290 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
1f2a0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
1f2b0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
1f2c0 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
1f2d0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
1f2e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1f2f0 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
1f300 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
1f310 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
1f320 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
1f330 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f340 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
1f350 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1f360 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
1f370 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
1f380 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
1f390 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
1f3a0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
1f3b0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  coding..**.** Th
1f3c0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
1f3d0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
1f3e0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
1f3f0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
1f400 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
1f410 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
1f420 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1f430 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77  nt to the follow
1f440 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b  ing calls is a [
1f450 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f460 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75  nt]..** These fu
1f470 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
1f480 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
1f490 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f4a0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
1f4b0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
1f4c0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1f4d0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
1f4e0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ument..**.** If 
1f4f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
1f500 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
1f510 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
1f520 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
1f530 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
1f540 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
1f550 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
1f560 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
1f570 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
1f580 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d   These routine m
1f590 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
1f5a0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
1f5b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1f5c0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f  or.** occurs.  O
1f5d0 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
1f5e0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
1f5f0 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
1f600 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a  atabase, table.*
1f610 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61  * and column tha
1f620 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
1f630 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
1f640 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
1f650 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
1f660 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
1f670 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77  hose postfixed w
1f680 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
1f690 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
1f6a0 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f  d strings, the o
1f6b0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
1f6c0 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e  eturn UTF-8. {EN
1f6d0 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41  D}.**.** These A
1f6e0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
1f6f0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
1f700 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
1f710 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
1f720 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
1f730 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
1f740 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
1f750 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  mbol defined..**
1f760 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20  .** {A13751}.** 
1f770 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
1f780 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
1f790 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
1f7a0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
1f7b0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
1f7c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f7d0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
1f7e0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
1f7f0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
1f800 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
1f810 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1f820 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 34 31 5d 20  ts:.** [H13741] 
1f830 5b 48 31 33 37 34 32 5d 20 5b 48 31 33 37 34 33  [H13742] [H13743
1f840 5d 20 5b 48 31 33 37 34 34 5d 20 5b 48 31 33 37  ] [H13744] [H137
1f850 34 35 5d 20 5b 48 31 33 37 34 36 5d 20 5b 48 31  45] [H13746] [H1
1f860 33 37 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  3748].**.** If t
1f870 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
1f880 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
1f890 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
1f8a0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
1f8b0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
1f8c0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
1f8d0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
1f8e0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
1f8f0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
1f900 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
1f910 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
1f920 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
1f930 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
1f940 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1f950 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1f960 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
1f970 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1f980 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1f990 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
1f9a0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
1f9b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
1f9c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1f9d0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
1f9e0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1f9f0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
1fa00 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
1fa10 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
1fa20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1fa30 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1fa40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
1fa50 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
1fa60 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
1fa70 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1fa80 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
1fa90 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
1faa0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
1fab0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
1fac0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
1fad0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20   A Query Result 
1fae0 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30  {H13760} <S10700
1faf0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  >.**.** The firs
1fb00 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
1fb10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1fb20 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
1fb30 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
1fb40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1fb50 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
1fb60 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
1fb70 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
1fb80 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
1fb90 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
1fba0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
1fbb0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
1fbc0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
1fbd0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
1fbe0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
1fbf0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
1fc00 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74  rned.  If the Nt
1fc10 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
1fc20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
1fc30 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
1fc40 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
1fc50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1fc60 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
1fc70 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
1fc80 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
1fc90 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e  F-8 encoded. {EN
1fca0 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  D}.**.** For exa
1fcb0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
1fcc0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
1fcd0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
1fce0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
1fcf0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
1fd00 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
1fd10 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
1fd20 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
1fd30 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
1fd40 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
1fd50 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
1fd60 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
1fd70 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
1fd80 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
1fd90 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
1fda0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
1fdb0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
1fdc0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
1fdd0 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a  mn (i==0)..**.**
1fde0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
1fdf0 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
1fe00 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62  ping.  So just b
1fe10 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
1fe20 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
1fe30 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
1fe40 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
1fe50 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
1fe60 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
1fe70 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
1fe80 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
1fe90 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
1fea0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
1feb0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
1fec0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
1fed0 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54  c not static.  T
1fee0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
1fef0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
1ff00 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
1ff10 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
1ff20 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
1ff30 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
1ff40 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
1ff50 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 36  ments:.** [H1376
1ff60 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48 31 33  1] [H13762] [H13
1ff70 37 36 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  763].*/.const ch
1ff80 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
1ff90 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
1ffa0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1ffb0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1ffc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
1ffd0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
1ffe0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
1fff0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
20000 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
20010 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53  ment {H13200} <S
20020 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74  10000>.**.** Aft
20030 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
20040 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
20050 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
20060 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
20070 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
20080 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
20090 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
200a0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
200b0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
200c0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
200d0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
200e0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
200f0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
20100 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
20110 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
20120 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
20130 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
20140 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
20150 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
20160 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
20170 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
20180 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
20190 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
201a0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
201b0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
201c0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
201d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
201e0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
201f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20200 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
20210 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
20220 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
20230 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
20240 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20250 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
20260 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
20270 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
20280 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
20290 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
202a0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
202b0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
202c0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
202d0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
202e0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
202f0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
20300 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
20310 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
20320 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
20330 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
20340 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
20350 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
20360 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57  TE_MISUSE]..** W
20370 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
20380 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
20390 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
203a0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
203b0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
203c0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
203d0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
203e0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  .**.** [SQLITE_B
203f0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
20400 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
20410 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
20420 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
20430 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
20440 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
20450 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20  ts job.  If the 
20460 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
20470 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
20480 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
20490 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
204a0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
204b0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
204c0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
204d0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
204e0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
204f0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
20500 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
20510 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
20520 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
20530 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
20540 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
20550 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
20560 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
20570 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
20580 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
20590 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
205a0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
205b0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
205c0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
205d0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
205e0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
205f0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
20600 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
20610 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
20620 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
20630 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
20640 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
20650 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
20660 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
20670 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
20680 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
20690 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
206a0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
206b0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
206c0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
206d0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
206e0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
206f0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
20700 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
20710 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
20720 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
20730 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
20740 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
20750 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
20760 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
20770 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
20780 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
20790 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
207a0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
207b0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
207c0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
207d0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
207e0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
207f0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
20800 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
20810 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
20820 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
20830 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
20840 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
20850 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69  errmsg()]..** Wi
20860 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
20870 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
20880 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
20890 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
208a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
208b0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
208c0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
208d0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
208e0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
208f0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
20900 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
20910 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
20920 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
20930 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68  atement].  In th
20940 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
20950 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
20960 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
20970 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
20980 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
20990 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
209a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
209b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
209c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
209d0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
209e0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
209f0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
20a00 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
20a10 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
20a20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
20a30 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
20a40 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
20a50 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
20a60 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
20a70 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
20a80 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
20a90 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
20aa0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
20ab0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
20ac0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
20ad0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
20ae0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
20af0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
20b00 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
20b10 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
20b20 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
20b30 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
20b40 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
20b50 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
20b60 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
20b70 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
20b80 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
20b90 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
20ba0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
20bb0 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
20bc0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
20bd0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
20be0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
20bf0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
20c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
20c10 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
20c20 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
20c30 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
20c40 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
20c50 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
20c60 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
20c70 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
20c80 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
20c90 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
20ca0 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
20cb0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
20cc0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
20cd0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
20ce0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
20cf0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
20d00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
20d10 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
20d20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20d30 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
20d40 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
20d50 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
20d60 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
20d70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
20d80 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
20d90 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
20da0 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
20db0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
20dc0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
20dd0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
20de0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
20df0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
20e00 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
20e10 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
20e20 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  mmended..**.** R
20e30 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
20e40 5b 48 31 33 32 30 32 5d 20 5b 48 31 35 33 30 34  [H13202] [H15304
20e50 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48 31 35 33  ] [H15306] [H153
20e60 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a 2a 2f 0a  08] [H15310].*/.
20e70 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
20e80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
20e90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20ea0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
20eb0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
20ec0 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31  set {H13770} <S1
20ed0 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0700>.**.** Retu
20ee0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
20ef0 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20  f values in the 
20f00 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
20f10 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a  he result set..*
20f20 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
20f30 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 31 5d 20 5b  s:.** [H13771] [
20f40 48 31 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74 20 73  H13772].*/.int s
20f50 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
20f60 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
20f70 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
20f80 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
20f90 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b  ntal Datatypes {
20fa0 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e  H10265} <S10110>
20fb0 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57  <S10120>.** KEYW
20fc0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
20fd0 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d  T.**.** {H10266}
20fe0 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20   Every value in 
20ff0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
21000 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
21010 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
21020 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
21030 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
21040 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
21050 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
21060 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
21070 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
21080 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
21090 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
210a0 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  l> {END}.**.** T
210b0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
210c0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
210d0 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
210e0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
210f0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
21100 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
21110 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
21120 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
21130 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
21140 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
21150 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
21160 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
21170 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
21180 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
21190 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
211a0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
211b0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
211c0 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
211d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
211e0 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
211f0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
21200 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
21210 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
21220 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
21230 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
21240 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
21250 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
21260 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
21270 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
21280 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
21290 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
212a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
212b0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
212c0 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31  From A Query {H1
212d0 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3800} <S10700>.*
212e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
212f0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
21300 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
21310 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
21320 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20  the "result set 
21330 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65  query" interface
21340 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
21350 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
21360 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
21370 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
21380 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
21390 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
213a0 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65  a query.  In eve
213b0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
213c0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
213d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
213e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
213f0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
21400 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
21410 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
21420 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
21430 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
21440 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21450 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
21460 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
21470 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
21480 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
21490 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
214a0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
214b0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
214c0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
214d0 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   The leftmost co
214e0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
214f0 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
21500 6e 64 65 78 20 30 2e 0a 2a 2a 20 54 68 65 20 6e  ndex 0..** The n
21510 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
21520 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
21530 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
21540 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
21550 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
21560 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
21570 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
21580 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
21590 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
215a0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
215b0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
215c0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
215d0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
215e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
215f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
21600 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
21610 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
21620 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
21630 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21640 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
21650 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
21660 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
21670 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
21680 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
21690 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
216a0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
216b0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
216c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
216d0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
216e0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
216f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
21700 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
21710 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
21720 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
21730 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
21740 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
21750 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
21760 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
21770 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
21780 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
21790 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
217a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
217b0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
217c0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
217d0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
217e0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
217f0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
21800 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
21810 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
21820 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
21830 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
21840 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
21850 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
21860 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
21870 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
21880 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
21890 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
218a0 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
218b0 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74  column.  The ret
218c0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
218d0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
218e0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
218f0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
21900 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
21910 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
21920 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
21930 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
21940 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
21950 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
21960 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
21970 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
21980 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
21990 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
219a0 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
219b0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
219c0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
219d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
219e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
219f0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
21a00 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
21a10 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
21a20 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
21a30 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
21a40 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
21a50 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
21a60 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
21a70 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  **.** If the res
21a80 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
21a90 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
21aa0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
21ab0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
21ac0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
21ad0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
21ae0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
21af0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
21b00 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
21b10 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
21b20 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
21b30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
21b40 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
21b50 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
21b60 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
21b70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
21b80 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  es..** If the re
21b90 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
21ba0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
21bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21bc0 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
21bd0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
21be0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
21bf0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
21c00 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
21c10 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
21c20 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
21c30 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54  hat string..** T
21c40 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
21c50 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
21c60 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
21c70 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e  inator at the en
21c80 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
21c90 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79  ng.  For clarity
21ca0 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  : the value retu
21cb0 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62  rned is the numb
21cc0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
21cd0 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
21ce0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
21cf0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
21d00 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e  * Strings return
21d10 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
21d20 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
21d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21d40 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
21d50 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
21d60 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20  are always zero 
21d70 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
21d80 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
21d90 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
21da0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
21db0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
21dc0 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  OB is an arbitra
21dd0 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70  ry.** pointer, p
21de0 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e  ossibly even a N
21df0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
21e00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
21e10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
21e20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
21e30 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ar to sqlite3_co
21e40 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
21e50 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72  but leaves the r
21e60 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20  esult in UTF-16 
21e70 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
21e80 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  rder instead of 
21e90 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65  UTF-8..** The ze
21ea0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73  ro terminator is
21eb0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e   not included in
21ec0 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a   this count..**.
21ed0 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65  ** The object re
21ee0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
21ef0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
21f00 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
21f10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
21f20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
21f30 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
21f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
21f50 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
21f60 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
21f70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
21f80 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
21f90 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
21fa0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
21fb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
21fc0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
21fd0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
21fe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
21ff0 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
22000 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
22010 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
22020 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
22030 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
22040 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
22050 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
22060 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
22070 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
22080 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
22090 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
220a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
220b0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
220c0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
220d0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
220e0 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a  opriate.  For.**
220f0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
22100 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
22110 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
22120 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
22130 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
22140 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
22150 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
22160 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
22170 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
22180 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
22190 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f  tically.  The fo
221a0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
221b0 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
221c0 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
221d0 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
221e0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
221f0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
22200 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
22210 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
22220 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
22230 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
22240 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
22250 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
22260 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
22270 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
22280 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
22290 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
222a0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
222b0 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
222c0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
222d0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
222e0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
222f0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
22300 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
22310 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
22320 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
22330 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
22340 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
22350 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
22360 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
22370 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
22380 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
22390 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
223a0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
223b0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
223c0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
223d0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
223e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
223f0 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
22400 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
22410 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
22420 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
22430 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
22440 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
22450 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
22460 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
22470 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
22480 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
22490 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
224a0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
224b0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
224c0 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
224d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
224e0 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
224f0 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
22500 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
22510 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
22520 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
22530 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
22540 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
22550 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
22560 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
22570 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
22580 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
22590 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
225a0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
225b0 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
225c0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
225d0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
225e0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
225f0 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
22600 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
22610 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
22620 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
22630 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
22640 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
22650 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
22660 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  e>.**.** The tab
22670 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
22680 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
22690 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
226a0 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
226b0 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
226c0 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
226d0 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
226e0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
226f0 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
22700 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
22710 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
22720 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
22730 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
22740 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
22750 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
22760 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
22770 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
22780 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
22790 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
227a0 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
227b0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
227c0 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
227d0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
227e0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
227f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
22800 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
22810 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
22820 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
22830 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
22840 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
22850 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
22860 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
22870 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
22880 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
22890 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
228a0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
228b0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
228c0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
228d0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
228e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
228f0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
22900 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
22910 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
22920 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
22930 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
22940 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
22950 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
22960 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
22970 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
22980 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
22990 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
229a0 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
229b0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
229c0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
229d0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
229e0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
229f0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
22a00 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
22a10 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
22a20 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
22a30 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
22a40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
22a50 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
22a60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22a70 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
22a80 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
22a90 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
22aa0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
22ab0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
22ac0 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e  **.** Conversion
22ad0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
22ae0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
22af0 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
22b00 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
22b10 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
22b20 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
22b30 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
22b40 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
22b50 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
22b60 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
22b70 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74  pointer points t
22b80 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  o will have been
22b90 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
22ba0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
22bb0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
22bc0 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
22bd0 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
22be0 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
22bf0 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
22c00 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
22c10 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
22c20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
22c30 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
22c40 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
22c50 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
22c60 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
22c70 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
22c80 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
22c90 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
22ca0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
22cb0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
22cc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
22cd0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
22ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22cf0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
22d00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22d10 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
22d20 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
22d30 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
22d40 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
22d50 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
22d60 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
22d70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
22d80 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
22d90 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
22da0 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
22db0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
22dc0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
22dd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22de0 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
22df0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
22e00 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
22e10 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
22e20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
22e30 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
22e40 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
22e50 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
22e60 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
22e70 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
22e80 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
22e90 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
22ea0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
22eb0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
22ec0 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
22ed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
22ee0 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
22ef0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
22f00 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
22f10 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
22f20 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
22f30 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
22f40 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
22f50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
22f60 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  es()..**.** The 
22f70 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
22f80 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
22f90 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
22fa0 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
22fb0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
22fc0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
22fd0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
22fe0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
22ff0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
23000 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
23010 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f  alled.  The memo
23020 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
23030 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
23040 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
23050 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
23060 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
23070 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
23080 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
23090 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
230a0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
230b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
230c0 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
230d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
230e0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f  .**.** If a memo
230f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
23100 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
23110 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
23120 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
23130 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
23140 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
23150 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
23160 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
23170 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
23180 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
23190 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
231a0 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
231b0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
231c0 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
231d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
231e0 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
231f0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
23200 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  OMEM]..**.** Req
23210 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
23220 31 33 38 30 33 5d 20 5b 48 31 33 38 30 36 5d 20  13803] [H13806] 
23230 5b 48 31 33 38 30 39 5d 20 5b 48 31 33 38 31 32  [H13809] [H13812
23240 5d 20 5b 48 31 33 38 31 35 5d 20 5b 48 31 33 38  ] [H13815] [H138
23250 31 38 5d 20 5b 48 31 33 38 32 31 5d 20 5b 48 31  18] [H13821] [H1
23260 33 38 32 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37  3824].** [H13827
23270 5d 20 5b 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f  ] [H13830].*/.co
23280 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
23290 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
232a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
232b0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
232c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
232d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
232e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
232f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23300 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
23310 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
23320 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
23330 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
23340 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23350 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
23360 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
23370 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23380 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
23390 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
233a0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
233b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
233c0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
233d0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
233e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
233f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23400 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
23410 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
23420 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
23430 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
23440 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
23450 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
23460 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
23470 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
23480 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
23490 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
234a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
234b0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
234c0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
234d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
234e0 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30  t Object {H13300
234f0 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30  } <S70300><S3010
23500 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
23510 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
23520 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
23530 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
23540 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23550 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  nt]..** If the s
23560 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65  tatement was exe
23570 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c  cuted successful
23580 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74  ly or not execut
23590 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a  ed at all, then.
235a0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  ** SQLITE_OK is 
235b0 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65  returned. If exe
235c0 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  cution of the st
235d0 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74  atement failed t
235e0 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72  hen an.** [error
235f0 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
23600 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
23610 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
23620 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
23630 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
23640 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
23650 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
23660 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  of the.** [prepa
23670 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
23680 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   If the virtual 
23690 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a  machine has not.
236a0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
236b0 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73  cution when this
236c0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
236d0 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65  ed, that is like
236e0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  .** encountering
236f0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20   an error or an 
23700 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
23710 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e  pt | interrupt].
23720 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75  .** Incomplete u
23730 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f  pdates may be ro
23740 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72  lled back and tr
23750 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65  ansactions cance
23760 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  led,.** dependin
23770 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73  g on the circums
23780 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a  tances, and the.
23790 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
237a0 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65  returned will be
237b0 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
237c0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
237d0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d  nts:.** [H11302]
237e0 20 5b 48 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74   [H11304].*/.int
237f0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
23800 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
23810 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
23820 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
23830 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
23840 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33  ent Object {H133
23850 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  30} <S70300>.**.
23860 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
23870 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
23880 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
23890 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
238a0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
238b0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
238c0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
238d0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
238e0 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53  ecuted..** Any S
238f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
23900 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
23910 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
23920 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
23930 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
23940 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
23950 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
23960 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
23970 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
23980 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
23990 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
239a0 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
239b0 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73   {H11332} The [s
239c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
239d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
239e0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
239f0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
23a00 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f           back to
23a10 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
23a20 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
23a30 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66  *.** {H11334} If
23a40 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23a50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
23a60 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
23a70 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
23a80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23a90 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
23aa0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
23ab0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
23ac0 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
23ad0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
23ae0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
23af0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
23b00 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  n S,.**         
23b10 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
23b20 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
23b30 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
23b40 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20  .** {H11336} If 
23b50 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
23b60 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
23b70 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
23b80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
23b90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23ba0 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
23bb0 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
23bc0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
23bd0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
23be0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
23bf0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
23c00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d  ..**.** {H11338}
23c10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
23c20 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
23c30 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
23c40 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
23c50 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20           of any 
23c60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
23c70 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
23c80 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23c90 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
23ca0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
23cb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
23cc0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
23cd0 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
23ce0 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
23cf0 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30  unctions {H16100
23d00 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45  } <S20200>.** KE
23d10 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
23d20 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
23d30 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
23d40 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
23d50 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
23d60 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
23d70 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
23d80 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
23d90 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
23da0 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  e two functions 
23db0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
23dc0 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
23dd0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
23de0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
23df0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
23e00 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
23e10 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
23e20 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
23e30 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
23e40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
23e50 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
23e60 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
23e70 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20   between the.** 
23e80 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20  two is that the 
23e90 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
23ea0 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
23eb0 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
23ec0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
23ed0 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20  ate, is encoded 
23ee0 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c  in UTF-8 for sql
23ef0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
23f00 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
23f10 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  6.** for sqlite3
23f20 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23f30 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
23f40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
23f50 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
23f60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
23f70 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
23f80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
23f90 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20  be added.  If a 
23fa0 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75  single program u
23fb0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
23fc0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
23fd0 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61  nnection interna
23fe0 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75  lly, then SQL fu
23ff0 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
24000 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c  added individual
24010 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61  ly to.** each da
24020 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24030 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  n..**.** The sec
24040 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
24050 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24060 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
24070 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
24080 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68  * redefined.  Th
24090 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
240a0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
240b0 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
240c0 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68  clusive of.** th
240d0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
240e0 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  r.  Note that th
240f0 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69  e name length li
24100 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c  mit is in bytes,
24110 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65   not.** characte
24120 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74  rs.  Any attempt
24130 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
24140 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
24150 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
24160 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
24170 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20  TE_ERROR] being 
24180 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
24190 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
241a0 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
241b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
241c0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
241d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
241e0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
241f0 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61  akes. If this pa
24200 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
24210 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
24220 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
24230 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
24240 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
24250 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
24260 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
24270 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
24280 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
24290 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
242a0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
242b0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
242c0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
242d0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
242e0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
242f0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
24300 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
24310 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
24320 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
24330 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
24340 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
24350 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
24360 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
24370 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
24380 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
24390 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
243a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
243b0 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
243c0 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
243d0 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
243e0 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
243f0 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
24400 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
24410 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
24420 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
24430 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
24440 68 65 72 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  her.  An applica
24450 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f  tion may.** invo
24460 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
24470 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
24480 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24490 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
244a0 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
244b0 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
244c0 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
244d0 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
244e0 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57  f eTextRep..** W
244f0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
24500 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
24510 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
24520 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
24530 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
24540 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
24550 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
24560 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
24570 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
24580 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f  ** If there is o
24590 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70  nly a single imp
245a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63  lementation whic
245b0 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  h does not care 
245c0 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63  what text.** enc
245d0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  oding is used, t
245e0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61  hen the fourth a
245f0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
24600 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  e [SQLITE_ANY]..
24610 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20  **.** The fifth 
24620 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
24630 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
24640 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
24650 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
24660 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
24670 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
24680 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
24690 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
246a0 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ta()]..**.** The
246b0 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
246c0 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
246d0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
246e0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
246f0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
24700 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
24710 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
24720 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
24730 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
24740 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61  gregate. A scala
24750 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
24760 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
24770 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
24780 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
24790 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f  ck only, NULL po
247a0 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
247b0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
247c0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
247d0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41  ** parameters. A
247e0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
247f0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
24800 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
24810 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
24820 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
24830 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ULL should be pa
24840 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
24850 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
24860 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
24870 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
24880 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
24890 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
248a0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  tion callbacks..
248b0 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d  **.** It is perm
248c0 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
248d0 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
248e0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
248f0 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
24900 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
24910 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
24920 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
24930 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
24940 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
24950 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
24960 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
24970 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
24980 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
24990 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
249a0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
249b0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
249c0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
249d0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
249e0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
249f0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
24a00 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
24a10 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
24a20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
24a30 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
24a40 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
24a50 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
24a60 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75 6e  ive nArg.  A fun
24a70 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
24a80 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
24a90 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
24aa0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
24ab0 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
24ac0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
24ad0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
24ae0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
24af0 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
24b00 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20 77  .** A function w
24b10 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
24b20 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
24b30 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
24b40 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
24b50 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
24b60 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
24b70 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
24b80 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
24b90 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
24ba0 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
24bb0 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  ** Built-in func
24bc0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
24bd0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
24be0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
24bf0 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
24c00 20 54 68 65 20 66 69 72 73 74 20 61 70 70 6c 69   The first appli
24c10 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
24c20 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 67  unction with a g
24c30 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69  iven name overri
24c40 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74  des all.** built
24c50 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e  -in functions in
24c60 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
24c70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24c80 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
24c90 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  me..** Subsequen
24ca0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  t application-de
24cb0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20  fined functions 
24cc0 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  of the same name
24cd0 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a   only override .
24ce0 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61  ** prior applica
24cf0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
24d00 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ctions that are 
24d10 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20 66  an exact match f
24d20 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  or the.** number
24d30 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 61   of parameters a
24d40 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e 63  nd preferred enc
24d50 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  oding..**.** An 
24d60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
24d70 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
24d80 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
24d90 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
24da0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
24db0 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
24dc0 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
24dd0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
24de0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
24df0 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
24e00 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
24e10 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
24e20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
24e30 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
24e40 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
24e50 73 3a 0a 2a 2a 20 5b 48 31 36 31 30 33 5d 20 5b  s:.** [H16103] [
24e60 48 31 36 31 30 36 5d 20 5b 48 31 36 31 30 39 5d  H16106] [H16109]
24e70 20 5b 48 31 36 31 31 32 5d 20 5b 48 31 36 31 31   [H16112] [H1611
24e80 38 5d 20 5b 48 31 36 31 32 31 5d 20 5b 48 31 36  8] [H16121] [H16
24e90 31 32 37 5d 0a 2a 2a 20 5b 48 31 36 31 33 30 5d  127].** [H16130]
24ea0 20 5b 48 31 36 31 33 33 5d 20 5b 48 31 36 31 33   [H16133] [H1613
24eb0 36 5d 20 5b 48 31 36 31 33 39 5d 20 5b 48 31 36  6] [H16139] [H16
24ec0 31 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  142].*/.int sqli
24ed0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
24ee0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
24ef0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
24f00 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
24f10 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
24f20 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
24f30 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
24f40 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
24f50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
24f60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
24f70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
24f80 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
24f90 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
24fa0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
24fb0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
24fc0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
24fd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
24fe0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
24ff0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
25000 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
25010 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
25020 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
25030 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
25040 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
25050 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
25060 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
25070 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
25080 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
25090 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
250a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
250b0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
250c0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
250d0 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  xt*).);../*.** C
250e0 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
250f0 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37 7d  codings {H10267}
25100 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31 30   <S50200> <H1610
25110 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  0>.**.** These c
25120 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
25130 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
25140 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
25150 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
25160 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
25170 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
25180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
25190 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
251a0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
251b0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
251c0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
251d0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
251e0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
251f0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
25200 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
25210 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
25220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25230 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
25240 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
25250 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
25260 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
25270 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
25280 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
25290 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
252a0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
252b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
252c0 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
252d0 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
252e0 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
252f0 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
25300 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
25310 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
25320 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
25330 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
25340 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
25350 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
25360 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
25370 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
25380 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
25390 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
253a0 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
253b0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
253c0 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72    To help encour
253d0 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76  age people to av
253e0 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  oid.** using the
253f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
25400 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74   are not going t
25410 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20  o tell you what 
25420 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
25430 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
25440 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
25450 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
25460 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
25470 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
25480 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
25490 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
254a0 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
254b0 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
254c0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
254d0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
254e0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
254f0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
25500 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
25510 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
25520 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
25530 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
25540 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
25550 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
25560 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
25570 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
25580 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
25590 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
255a0 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
255b0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
255c0 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
255d0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
255e0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
255f0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
25600 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
25610 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31 35  eter Values {H15
25620 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  100} <S20200>.**
25630 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
25640 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
25650 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
25660 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
25670 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
25680 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
25690 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
256a0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
256b0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
256c0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
256d0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
256e0 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
256f0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
25700 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
25710 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
25720 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
25730 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25740 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
25750 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25760 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
25770 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
25780 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
25790 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
257a0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
257b0 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
257c0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
257d0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
257e0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
257f0 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
25800 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25810 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
25820 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
25830 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
25840 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
25850 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
25860 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
25870 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
25880 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
25890 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
258a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
258b0 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
258c0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
258d0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
258e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
258f0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
25900 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
25910 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
25920 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
25930 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25940 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
25950 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
25960 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
25970 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
25980 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
25990 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
259a0 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
259b0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
259c0 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
259d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
259e0 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
259f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25a00 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
25a10 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
25a20 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
25a30 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
25a40 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
25a50 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
25a60 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
25a70 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
25a80 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
25a90 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
25aa0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
25ab0 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
25ac0 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
25ad0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
25ae0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
25af0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
25b00 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
25b10 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
25b20 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
25b30 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
25b40 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
25b50 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
25b60 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
25b70 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
25b80 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
25b90 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
25ba0 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
25bb0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
25bc0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
25bd0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
25be0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
25bf0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
25c00 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
25c10 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
25c20 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
25c30 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
25c40 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
25c50 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
25c60 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
25c70 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
25c80 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
25c90 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
25ca0 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
25cb0 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
25cc0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
25cd0 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
25ce0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
25cf0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
25d00 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
25d10 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
25d20 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
25d30 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
25d40 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
25d50 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
25d60 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
25d70 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
25d80 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
25d90 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
25da0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25db0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
25dc0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
25dd0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
25de0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
25df0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
25e00 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
25e10 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
25e20 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
25e30 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
25e40 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
25e50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
25e60 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
25e70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
25e80 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
25e90 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
25ea0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
25eb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
25ec0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
25ed0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
25ee0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a   parameters..**.
25ef0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
25f00 0a 2a 2a 20 5b 48 31 35 31 30 33 5d 20 5b 48 31  .** [H15103] [H1
25f10 35 31 30 36 5d 20 5b 48 31 35 31 30 39 5d 20 5b  5106] [H15109] [
25f20 48 31 35 31 31 32 5d 20 5b 48 31 35 31 31 35 5d  H15112] [H15115]
25f30 20 5b 48 31 35 31 31 38 5d 20 5b 48 31 35 31 32   [H15118] [H1512
25f40 31 5d 20 5b 48 31 35 31 32 34 5d 0a 2a 2a 20 5b  1] [H15124].** [
25f50 48 31 35 31 32 37 5d 20 5b 48 31 35 31 33 30 5d  H15127] [H15130]
25f60 20 5b 48 31 35 31 33 33 5d 20 5b 48 31 35 31 33   [H15133] [H1513
25f70 36 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  6].*/.const void
25f80 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
25f90 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
25fa0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
25fb0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
25fc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
25fd0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
25fe0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
25ff0 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
26000 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
26010 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
26020 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
26030 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
26040 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
26050 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
26060 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
26070 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26080 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
26090 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
260a0 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
260b0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
260c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
260d0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
260e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
260f0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
26100 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
26110 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
26120 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
26130 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
26140 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
26150 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
26160 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
26170 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
26180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
26190 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
261a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
261b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
261c0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
261d0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b  nction Context {
261e0 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30 3e  H16210} <S20200>
261f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  .**.** The imple
26200 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67  mentation of agg
26210 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
26220 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f  ions use this ro
26230 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
26240 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65  e.** a structure
26250 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
26260 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
26270 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
26280 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
26290 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72  gate_context() r
262a0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
262b0 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63   for a.** partic
262c0 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20  ular aggregate, 
262d0 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73  SQLite allocates
262e0 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72   nBytes of memor
262f0 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
26300 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e  at.** memory, an
26310 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
26320 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65  ter to it. On se
26330 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
26340 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
26350 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
26360 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
26370 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
26380 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65  te function inde
26390 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  x,.** the same b
263a0 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
263b0 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  d. The implement
263c0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67  ation of the agg
263d0 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a  regate can use.*
263e0 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62  * the returned b
263f0 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c  uffer to accumul
26400 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  ate data..**.** 
26410 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
26420 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61  ally frees the a
26430 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20  llocated buffer 
26440 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
26450 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63  te.** query conc
26460 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
26470 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
26480 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70   should be a cop
26490 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
264a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
264b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
264c0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
264d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
264e0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
264f0 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
26500 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
26510 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
26520 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
26530 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
26540 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
26550 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
26560 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
26570 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
26580 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
26590 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
265a0 3a 0a 2a 2a 20 5b 48 31 36 32 31 31 5d 20 5b 48  :.** [H16211] [H
265b0 31 36 32 31 33 5d 20 5b 48 31 36 32 31 35 5d 20  16213] [H16215] 
265c0 5b 48 31 36 32 31 37 5d 0a 2a 2f 0a 76 6f 69 64  [H16217].*/.void
265d0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
265e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
265f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
26600 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
26610 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
26620 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
26630 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53 32  ons {H16240} <S2
26640 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
26650 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
26660 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
26670 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
26680 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
26690 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
266a0 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
266b0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
266c0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
266d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
266e0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
266f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26700 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
26710 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
26720 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
26730 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
26740 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
26750 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a  nction. {END}.**
26760 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
26770 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
26780 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
26790 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
267a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
267b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
267c0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
267d0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
267e0 3a 0a 2a 2a 20 5b 48 31 36 32 34 33 5d 0a 2a 2f  :.** [H16243].*/
267f0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
26800 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
26810 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
26820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
26830 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
26840 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b   For Functions {
26850 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30 30 3e  H16250} <S60600>
26860 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
26870 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
26880 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
26890 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
268a0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
268b0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
268c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
268d0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
268e0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
268f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
26900 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
26910 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
26920 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26930 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
26940 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
26950 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
26960 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
26970 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
26980 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
26990 73 3a 0a 2a 2a 20 5b 48 31 36 32 35 33 5d 0a 2a  s:.** [H16253].*
269a0 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
269b0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
269c0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
269d0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
269e0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
269f0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
26a00 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32 30   {H16270} <S2020
26a10 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  0>.**.** The fol
26a20 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
26a30 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
26a40 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
26a50 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
26a60 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
26a70 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
26a80 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
26a90 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
26aa0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
26ab0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
26ac0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
26ad0 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
26ae0 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
26af0 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
26b00 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
26b10 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
26b20 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
26b30 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
26b40 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
26b50 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
26b60 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
26b70 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
26b80 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
26b90 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
26ba0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
26bb0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
26bc0 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
26bd0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
26be0 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
26bf0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
26c00 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
26c10 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
26c20 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
26c30 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
26c40 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
26c50 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
26c60 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
26c70 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
26c80 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
26c90 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
26ca0 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
26cb0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
26cc0 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
26cd0 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
26ce0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
26cf0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
26d00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
26d10 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
26d20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
26d30 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
26d40 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
26d50 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
26d60 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
26d70 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
26d80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
26d90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
26da0 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20   If no metadata 
26db0 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
26dc0 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
26dd0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
26de0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
26df0 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
26e00 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
26e10 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
26e20 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
26e30 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
26e40 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
26e50 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
26e60 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
26e70 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
26e80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
26e90 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
26ea0 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
26eb0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
26ec0 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
26ed0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
26ee0 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
26ef0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
26f00 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
26f10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26f20 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
26f30 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
26f40 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
26f50 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
26f60 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
26f70 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
26f80 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
26f90 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f  ..** If it is no
26fa0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
26fb0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
26fc0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
26fd0 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
26fe0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
26ff0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
27000 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
27010 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
27020 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
27030 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
27040 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
27050 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
27060 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
27070 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
27080 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
27090 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
270a0 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
270b0 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
270c0 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
270d0 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
270e0 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
270f0 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68  at any time.  Th
27100 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65  e only guarantee
27110 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20   is that.** the 
27120 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20  destructor will 
27130 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
27140 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
27150 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20   dropped..**.** 
27160 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
27170 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
27180 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
27190 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
271a0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
271b0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
271c0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
271d0 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
271e0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
271f0 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65  and SQL variable
27200 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
27210 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
27220 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
27230 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
27240 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
27250 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
27260 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
27270 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
27280 32 37 32 5d 20 5b 48 31 36 32 37 34 5d 20 5b 48  272] [H16274] [H
27290 31 36 32 37 36 5d 20 5b 48 31 36 32 37 37 5d 20  16276] [H16277] 
272a0 5b 48 31 36 32 37 38 5d 20 5b 48 31 36 32 37 39  [H16278] [H16279
272b0 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ].*/.void *sqlit
272c0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
272d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
272e0 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
272f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
27300 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
27310 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
27320 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
27330 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
27340 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
27350 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
27360 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
27370 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53  vior {H10280} <S
27380 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30100>.**.** The
27390 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
273a0 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
273b0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
273c0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
273d0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
273e0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
273f0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
27400 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49  sult_blob()].  I
27410 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
27420 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
27430 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
27440 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
27450 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
27460 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
27470 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
27480 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
27490 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
274a0 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a  estroyed.  The.*
274b0 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
274c0 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
274d0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
274e0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
274f0 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
27500 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
27510 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
27520 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
27530 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
27540 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
27550 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
27560 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
27570 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
27580 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
27590 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
275a0 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
275b0 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
275c0 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  191..*/.typedef 
275d0 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
275e0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
275f0 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
27600 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
27610 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
27620 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
27630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
27640 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
27650 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
27660 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
27670 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
27680 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
27690 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  An SQL Function 
276a0 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30  {H16400} <S20200
276b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
276c0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
276d0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
276e0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
276f0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
27700 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
27710 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
27720 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
27730 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27740 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
27750 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27760 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
27770 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
27780 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
27790 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
277a0 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
277b0 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
277c0 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
277d0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
277e0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
277f0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
27800 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
27810 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
27820 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
27830 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
27840 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
27850 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
27860 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
27870 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
27880 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
27890 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
278a0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
278b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
278c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
278d0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
278e0 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
278f0 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
27900 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
27910 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
27920 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
27930 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
27940 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
27950 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
27960 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
27970 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
27980 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
27990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
279a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
279b0 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
279c0 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
279d0 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
279e0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
279f0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
27a00 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
27a10 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
27a20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
27a30 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
27a40 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
27a50 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
27a60 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
27a70 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
27a80 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
27a90 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
27aa0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
27ab0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
27ac0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27ad0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
27ae0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
27af0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
27b00 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
27b10 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
27b20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
27b30 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
27b40 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  on..** SQLite us
27b50 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
27b60 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
27b70 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
27b80 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
27b90 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
27ba0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
27bb0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
27bc0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
27bd0 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69  r message.  SQLi
27be0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
27bf0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
27c00 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
27c10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
27c20 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
27c30 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
27c40 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
27c50 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
27c60 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
27c70 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
27c80 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
27c90 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70    If the third p
27ca0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27cb0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
27cc0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
27cd0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
27ce0 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
27cf0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
27d00 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
27d10 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
27d20 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
27d30 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
27d40 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
27d50 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
27d60 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
27d70 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
27d80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27d90 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
27da0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
27db0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
27dc0 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
27dd0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
27de0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
27df0 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
27e00 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54  or message..** T
27e10 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27e20 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
27e30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
27e40 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
27e50 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
27e60 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
27e70 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
27e80 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
27e90 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
27ea0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
27eb0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
27ec0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
27ed0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
27ee0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
27ef0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65  out harm..** The
27f00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27f10 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
27f20 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
27f30 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
27f40 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
27f50 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
27f60 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
27f70 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65  function.  By de
27f80 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
27f90 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
27fa0 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62  TE_ERROR.  A sub
27fb0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
27fc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27fd0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
27fe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
27ff0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
28000 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
28010 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
28020 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
28030 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
28040 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
28050 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
28060 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
28070 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
28080 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
28090 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  to long to repre
280a0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sent..**.** The 
280b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
280c0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
280d0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
280e0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
280f0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
28100 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
28110 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
28120 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28130 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
28140 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
28150 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
28160 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
28170 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
28180 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
28190 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
281a0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
281b0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
281c0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
281d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
281e0 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
281f0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
28200 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
28210 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
28220 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
28230 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
28240 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
28250 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
28260 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
28270 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
28280 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
28290 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
282a0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
282b0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
282c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
282d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
282e0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
282f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
28300 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
28310 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
28320 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
28330 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
28340 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28350 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
28360 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
28370 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
28380 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
28390 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
283a0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
283b0 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
283c0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
283d0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
283e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
283f0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
28400 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
28410 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
28420 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
28430 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  ** SQLite takes 
28440 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
28450 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
28460 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
28470 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
28480 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
28490 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
284a0 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  faces..** If the
284b0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
284c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
284d0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
284e0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
284f0 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
28500 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
28510 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
28520 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
28530 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
28540 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
28550 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
28560 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
28570 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
28580 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
28590 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
285a0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
285b0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
285c0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
285d0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
285e0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
285f0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
28600 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
28610 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
28620 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
28630 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
28640 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
28650 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
28660 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
28670 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
28680 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
28690 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
286a0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
286b0 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
286c0 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
286d0 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
286e0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
286f0 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
28700 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
28710 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
28720 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
28730 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
28740 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
28750 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
28760 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
28770 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
28780 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
28790 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
287a0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
287b0 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
287c0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
287d0 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
287e0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
287f0 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
28800 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
28810 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
28820 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
28830 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
28840 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
28850 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
28860 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
28870 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
28880 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
28890 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
288a0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
288b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
288c0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
288d0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
288e0 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
288f0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
28900 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
28910 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
28920 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
28930 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
28940 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
28950 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
28960 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
28970 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
28980 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
28990 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
289a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
289b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
289c0 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
289d0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
289e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
289f0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
28a00 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
28a10 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  er.  The.** sqli
28a20 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
28a30 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
28a40 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
28a50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
28a60 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
28a70 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
28a80 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
28a90 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
28aa0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
28ab0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
28ac0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28ad0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
28ae0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
28af0 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   A [protected sq
28b00 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
28b10 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
28b20 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
28b30 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
28b40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28b50 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
28b60 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
28b70 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
28b80 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
28b90 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
28ba0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
28bb0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
28bc0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
28bd0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
28be0 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
28bf0 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
28c00 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
28c10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
28c20 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
28c30 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
28c40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
28c50 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
28c60 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
28c70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
28c80 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
28c90 2a 20 5b 48 31 36 34 30 33 5d 20 5b 48 31 36 34  * [H16403] [H164
28ca0 30 36 5d 20 5b 48 31 36 34 30 39 5d 20 5b 48 31  06] [H16409] [H1
28cb0 36 34 31 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b  6412] [H16415] [
28cc0 48 31 36 34 31 38 5d 20 5b 48 31 36 34 32 31 5d  H16418] [H16421]
28cd0 20 5b 48 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31   [H16424].** [H1
28ce0 36 34 32 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b  6427] [H16430] [
28cf0 48 31 36 34 33 33 5d 20 5b 48 31 36 34 33 36 5d  H16433] [H16436]
28d00 20 5b 48 31 36 34 33 39 5d 20 5b 48 31 36 34 34   [H16439] [H1644
28d10 32 5d 20 5b 48 31 36 34 34 35 5d 20 5b 48 31 36  2] [H16445] [H16
28d20 34 34 38 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d  448].** [H16451]
28d30 20 5b 48 31 36 34 35 34 5d 20 5b 48 31 36 34 35   [H16454] [H1645
28d40 37 5d 20 5b 48 31 36 34 36 30 5d 20 5b 48 31 36  7] [H16460] [H16
28d50 34 36 33 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  463].*/.void sql
28d60 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
28d70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28d80 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
28d90 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
28da0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
28db0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
28dc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28dd0 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
28de0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28df0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
28e00 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
28e10 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
28e20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
28e30 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
28e40 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
28e50 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
28e60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28e70 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
28e80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
28e90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
28ea0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
28eb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28ec0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
28ed0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
28ee0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
28ef0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
28f00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
28f10 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
28f20 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
28f30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
28f40 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
28f50 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
28f60 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
28f70 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
28f80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
28f90 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
28fa0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
28fb0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
28fc0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
28fd0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
28fe0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
28ff0 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
29000 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
29010 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
29020 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29030 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29040 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
29050 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
29060 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
29070 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
29080 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
29090 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
290a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
290b0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
290c0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
290d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
290e0 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
290f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
29100 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
29110 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
29120 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
29130 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
29140 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
29150 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
29160 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
29170 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c  ences {H16600} <
29180 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20300>.**.** Th
29190 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
291a0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
291b0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
291c0 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
291d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
291e0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
291f0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
29200 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
29210 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77   name of the new
29220 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
29230 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64  nce is specified
29240 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   as a UTF-8 stri
29250 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
29260 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
29270 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
29280 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29290 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
292a0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f  UTF-16 string fo
292b0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
292c0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20  _collation16(). 
292d0 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
292e0 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
292f0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
29300 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
29310 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  nt..**.** The th
29320 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  ird argument may
29330 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
29340 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
29350 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _UTF8],.** [SQLI
29360 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20  TE_UTF16LE], or 
29370 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
29380 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  , indicating tha
29390 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c  t the user-suppl
293a0 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65  ied.** routine e
293b0 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73  xpects to be pas
293c0 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  sed pointers to 
293d0 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20  strings encoded 
293e0 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20  using UTF-8,.** 
293f0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
29400 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
29410 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70  big-endian, resp
29420 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a  ectively. The.**
29430 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
29440 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53  might also be [S
29450 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 6f 20  QLITE_UTF16] to 
29460 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 74 68  indicate that th
29470 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70  e routine.** exp
29480 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f  ects pointers to
29490 20 62 65 20 55 54 46 2d 31 36 20 73 74 72 69 6e   be UTF-16 strin
294a0 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  gs in the native
294b0 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f 72 20   byte order, or 
294c0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
294d0 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  can be [SQLITE_U
294e0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66  TF16_ALIGNED] if
294f0 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74   the.** the rout
29500 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e  ine expects poin
29510 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77  ters to 16-bit w
29520 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69  ord aligned stri
29530 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36  ngs.** of UTF-16
29540 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
29550 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
29560 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
29570 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20  e user supplied 
29580 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
29590 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
295a0 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  fth.** argument.
295b0 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c    If it is NULL,
295c0 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   this is the sam
295d0 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68  e as deleting th
295e0 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
295f0 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74  equence (so that
29600 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63   SQLite cannot c
29610 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e  all it anymore).
29620 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68  .** Each time th
29630 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75  e application su
29640 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20  pplied function 
29650 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69  is invoked, it i
29660 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69  s passed.** as i
29670 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ts first paramet
29680 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  er a copy of the
29690 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73   void* passed as
296a0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
296b0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
296c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
296d0 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
296e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
296f0 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
29700 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d   remaining argum
29710 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c  ents to the appl
29720 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
29730 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f   routine are two
29740 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63   strings,.** eac
29750 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  h represented by
29760 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61   a (length, data
29770 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64  ) pair and encod
29780 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  ed in the encodi
29790 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70  ng.** that was p
297a0 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
297b0 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e  rd argument when
297c0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   the collation s
297d0 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72  equence was.** r
297e0 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d  egistered. {END}
297f0 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
29800 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  n defined collat
29810 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  ion routine shou
29820 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67  ld.** return neg
29830 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70  ative, zero or p
29840 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66  ositive if the f
29850 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
29860 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75  ess than,.** equ
29870 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
29880 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
29890 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28  d string. i.e. (
298a0 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47  STRING1 - STRING
298b0 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  2)..**.** The sq
298c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
298d0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
298e0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
298f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
29900 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
29910 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
29920 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
29930 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
29940 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
29950 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73  lation.  The des
29960 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
29970 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  d when the colla
29980 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72  tion is.** destr
29990 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73  oyed and is pass
299a0 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
299b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
299c0 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a  r void* pointer.
299d0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
299e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
299f0 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c  on_v2()..** Coll
29a00 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72  ations are destr
29a10 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  oyed when they a
29a20 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
29a30 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20   later calls to 
29a40 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e  the.** collation
29a50 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
29a60 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ons or when the 
29a70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29a80 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a  tion] is closed.
29a90 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
29aa0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
29ab0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71  * See also:  [sq
29ac0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
29ad0 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73  needed()] and [s
29ae0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
29af0 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a  _needed16()]..**
29b00 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
29b10 3a 0a 2a 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48  :.** [H16603] [H
29b20 31 36 36 30 34 5d 20 5b 48 31 36 36 30 36 5d 20  16604] [H16606] 
29b30 5b 48 31 36 36 30 39 5d 20 5b 48 31 36 36 31 32  [H16609] [H16612
29b40 5d 20 5b 48 31 36 36 31 35 5d 20 5b 48 31 36 36  ] [H16615] [H166
29b50 31 38 5d 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20  18] [H16621].** 
29b60 5b 48 31 36 36 32 34 5d 20 5b 48 31 36 36 32 37  [H16624] [H16627
29b70 5d 20 5b 48 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e  ] [H16630].*/.in
29b80 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
29b90 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
29ba0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
29bb0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
29bc0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
29bd0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
29be0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
29bf0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
29c00 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
29c10 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
29c20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
29c30 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
29c40 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
29c50 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
29c60 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
29c70 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
29c80 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
29c90 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
29ca0 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
29cb0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
29cc0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
29cd0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
29ce0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
29cf0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
29d00 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
29d10 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
29d20 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
29d30 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
29d40 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
29d50 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
29d60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
29d70 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
29d80 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30  Callbacks {H1670
29d90 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S20300>.**.*
29da0 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e  * To avoid havin
29db0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
29dc0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
29dd0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
29de0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
29df0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
29e00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
29e10 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
29e20 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
29e30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29e40 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c  ction] to be cal
29e50 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  led whenever an 
29e60 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
29e70 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
29e80 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
29e90 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69  ** If the functi
29ea0 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
29eb0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
29ec0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
29ed0 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
29ee0 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
29ef0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
29f00 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
29f10 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
29f20 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
29f30 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37   in UTF-8. {H167
29f40 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63  03} If sqlite3_c
29f50 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
29f60 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
29f70 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
29f80 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
29f90 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
29fa0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
29fb0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
29fc0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
29fd0 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20  es any existing 
29fe0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
29ff0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
2a000 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
2a010 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2a020 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
2a030 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
2a040 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
2a050 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2a060 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
2a070 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a080 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
2a090 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2a0a0 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
2a0b0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2a0c0 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
2a0d0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
2a0e0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
2a0f0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2a100 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
2a110 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
2a120 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
2a130 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
2a140 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
2a150 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
2a160 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
2a170 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2a180 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2a190 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
2a1a0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2a1b0 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  nce..**.** The c
2a1c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2a1d0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
2a1e0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
2a1f0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
2a200 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a210 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
2a220 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a230 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
2a240 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2a250 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2a260 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
2a270 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
2a280 37 30 32 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48  702] [H16704] [H
2a290 31 36 37 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71  16706].*/.int sq
2a2a0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2a2b0 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
2a2c0 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
2a2d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
2a2e0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
2a2f0 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
2a300 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2a310 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2a320 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
2a330 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
2a340 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2a350 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
2a360 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2a370 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
2a380 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
2a390 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
2a3a0 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
2a3b0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
2a3c0 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
2a3d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
2a3e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2a3f0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2a400 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2a410 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2a420 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2a430 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2a440 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2a450 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2a460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a470 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2a480 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2a490 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2a4a0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2a4b0 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2a4c0 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2a4d0 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2a4e0 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2a4f0 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2a500 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2a510 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2a520 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2a530 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2a540 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2a550 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2a560 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2a570 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2a580 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2a590 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2a5a0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2a5b0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2a5c0 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2a5d0 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
2a5e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2a5f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2a600 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2a610 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2a620 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2a630 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2a640 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
2a650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a660 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
2a670 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
2a680 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34  ime {H10530} <S4
2a690 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0410>.**.** The 
2a6a0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
2a6b0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
2a6c0 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
2a6d0 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
2a6e0 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
2a6f0 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
2a700 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
2a710 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
2a720 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
2a730 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
2a740 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
2a750 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
2a760 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
2a770 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
2a780 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
2a790 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
2a7a0 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
2a7b0 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
2a7c0 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
2a7d0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
2a7e0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
2a7f0 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
2a800 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
2a810 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
2a820 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2a830 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
2a840 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
2a850 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
2a860 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
2a870 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
2a880 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
2a890 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
2a8a0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48  Requirements: [H
2a8b0 31 30 35 33 33 5d 20 5b 48 31 30 35 33 36 5d 0a  10533] [H10536].
2a8c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2a8d0 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
2a8e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2a8f0 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
2a900 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
2a910 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20   Files {H10310} 
2a920 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49  <S20000>.**.** I
2a930 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
2a940 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
2a950 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
2a960 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
2a970 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
2a980 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
2a990 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
2a9a0 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
2a9b0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
2a9c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70  SQLite will be p
2a9d0 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
2a9e0 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69  rectory.  If thi
2a9f0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
2aa00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
2aa10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
2aa20 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
2aa30 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
2aa40 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
2aa50 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
2aa60 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
2aa70 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
2aa80 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2aa90 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
2aaa0 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
2aab0 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
2aac0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
2aad0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
2aae0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
2aaf0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2ab00 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
2ab10 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
2ab20 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
2ab30 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
2ab40 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
2ab50 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
2ab60 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
2ab70 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
2ab80 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
2ab90 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
2aba0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
2abb0 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
2abc0 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
2abd0 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
2abe0 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
2abf0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
2ac00 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
2ac10 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  The [temp_store_
2ac20 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2ac30 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
2ac40 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
2ac50 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
2ac60 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
2ac70 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2ac80 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46  ite3_malloc].  F
2ac90 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
2aca0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2acb0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2acc0 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
2acd0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
2ace0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
2acf0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
2ad00 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
2ad10 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2ad20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
2ad30 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
2ad40 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
2ad50 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
2ad60 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
2ad70 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
2ad80 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
2ad90 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
2ada0 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
2adb0 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
2adc0 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
2add0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
2ade0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
2adf0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2ae00 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
2ae10 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
2ae20 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2ae30 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2ae40 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
2ae50 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  ed..*/.SQLITE_EX
2ae60 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
2ae70 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
2ae80 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
2ae90 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
2aea0 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48  o-Commit Mode {H
2aeb0 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a  12930} <S60200>.
2aec0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
2aed0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a  tocommit mode}.*
2aee0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2aef0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2af00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2af10 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
2af20 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
2af30 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
2af40 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
2af50 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
2af60 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
2af70 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74 6f  pectively.  Auto
2af80 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
2af90 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
2afa0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
2afb0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
2afc0 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
2afd0 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d  ent..** Autocomm
2afe0 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
2aff0 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
2b000 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
2b010 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
2b020 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
2b030 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
2b040 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
2b050 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
2b060 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
2b070 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69   (errors includi
2b080 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d  ng [SQLITE_FULL]
2b090 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  , [SQLITE_IOERR]
2b0a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ,.** [SQLITE_NOM
2b0b0 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  EM], [SQLITE_BUS
2b0c0 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  Y], and [SQLITE_
2b0d0 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e  INTERRUPT]) then
2b0e0 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74   the.** transact
2b0f0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c  ion might be rol
2b100 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
2b110 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c  ically.  The onl
2b120 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64  y way to.** find
2b130 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c   out whether SQL
2b140 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
2b150 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
2b160 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
2b170 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
2b180 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
2b190 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
2b1a0 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
2b1b0 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74   changes the aut
2b1c0 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f  ocommit status o
2b1d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
2b1e0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  * connection whi
2b1f0 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
2b200 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e  is running, then
2b210 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2b220 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
2b230 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
2b240 6d 65 6e 74 73 3a 20 5b 48 31 32 39 33 31 5d 20  ments: [H12931] 
2b250 5b 48 31 32 39 33 32 5d 20 5b 48 31 32 39 33 33  [H12932] [H12933
2b260 5d 20 5b 48 31 32 39 33 34 5d 0a 2a 2f 0a 69 6e  ] [H12934].*/.in
2b270 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
2b280 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
2b290 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2b2a0 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
2b2b0 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
2b2c0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2b2d0 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c  ement {H13120} <
2b2e0 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60600>.**.** Th
2b2f0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  e sqlite3_db_han
2b300 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65  dle interface re
2b310 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62  turns the [datab
2b320 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2b330 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69  handle.** to whi
2b340 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ch a [prepared s
2b350 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67  tatement] belong
2b360 73 2e 20 20 54 68 65 20 5b 64 61 74 61 62 61 73  s.  The [databas
2b370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
2b380 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2b390 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
2b3a0 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  s the same [data
2b3b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b3c0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
2b3d0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
2b3e0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2b3f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
2b400 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
2b410 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
2b420 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
2b430 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
2b440 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
2b450 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
2b460 65 6e 74 73 3a 20 5b 48 31 33 31 32 33 5d 0a 2a  ents: [H13123].*
2b470 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
2b480 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  e3_db_handle(sql
2b490 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2b4a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
2b4b0 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  nd the next prep
2b4c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b  ared statement {
2b4d0 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30 3e  H13140} <S60600>
2b4e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2b4f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2b500 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
2b510 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
2b520 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
2b530 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
2b540 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
2b550 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b560 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74  ] pDb.  If pStmt
2b570 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e   is NULL.** then
2b580 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2b590 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2b5a0 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70  r to the first p
2b5b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b5c0 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  t.** associated 
2b5d0 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
2b5e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62  e connection pDb
2b5f0 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65  .  If no prepare
2b600 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73  d statement.** s
2b610 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e  atisfies the con
2b620 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20  ditions of this 
2b630 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75  routine, it retu
2b640 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  rns NULL..**.** 
2b650 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
2b660 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65  nnection] pointe
2b670 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r D in a call to
2b680 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  .** [sqlite3_nex
2b690 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73  t_stmt(D,S)] mus
2b6a0 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70  t refer to an op
2b6b0 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  en database.** c
2b6c0 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e  onnection and in
2b6d0 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74   particular must
2b6e0 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70   not be a NULL p
2b6f0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65  ointer..**.** Re
2b700 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33  quirements: [H13
2b710 31 34 33 5d 20 5b 48 31 33 31 34 36 5d 20 5b 48  143] [H13146] [H
2b720 31 33 31 34 39 5d 20 5b 48 31 33 31 35 32 5d 0a  13149] [H13152].
2b730 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  */.sqlite3_stmt 
2b740 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  *sqlite3_next_st
2b750 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c  mt(sqlite3 *pDb,
2b760 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70   sqlite3_stmt *p
2b770 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2b780 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
2b790 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
2b7a0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
2b7b0 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30  ks {H12950} <S60
2b7c0 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  400>.**.** The s
2b7d0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2b7e0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2b7f0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2b800 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
2b810 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2b820 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
2b830 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
2b840 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
2b850 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
2b860 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
2b870 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2b880 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
2b890 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
2b8a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b8b0 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
2b8c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2b8d0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
2b8e0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2b8f0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
2b900 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
2b910 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2b920 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
2b930 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  is [ROLLBACK | r
2b940 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20  olled back]..** 
2b950 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
2b960 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
2b970 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
2b980 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
2b990 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2b9a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b9b0 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2b9c0 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67 75  ** The pArg argu
2b9d0 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
2b9e0 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
2b9f0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68  llback..** If th
2ba00 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
2ba10 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
2ba20 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
2ba30 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
2ba40 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
2ba50 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
2ba60 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66  llback..**.** If
2ba70 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f   another functio
2ba80 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  n was previously
2ba90 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73   registered, its
2baa0 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69  .** pArg value i
2bab0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
2bac0 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72  erwise NULL is r
2bad0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2bae0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c  he callback impl
2baf0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
2bb00 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
2bb10 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
2bb20 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2bb30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2bb40 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c   invoked the cal
2bb50 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69  lback.  Any acti
2bb60 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
2bb70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2bb80 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
2bb90 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
2bba0 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
2bbb0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
2bbc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2bbd0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
2bbe0 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a  red the commit.*
2bbf0 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  * or rollback ho
2bc00 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ok in the first 
2bc10 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  place..** Note t
2bc20 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
2bc30 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
2bc40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2bc50 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
2bc60 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
2bc70 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
2bc80 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
2bc90 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
2bca0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52  ragraph..**.** R
2bcb0 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
2bcc0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
2bcd0 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
2bce0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
2bcf0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
2bd00 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
2bd10 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
2bd20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72  [COMMIT].** oper
2bd30 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64  ation is allowed
2bd40 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72   to continue nor
2bd50 6d 61 6c 6c 79 2e 20 20 49 66 20 74 68 65 20 63  mally.  If the c
2bd60 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65  ommit hook.** re
2bd70 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
2bd80 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54  then the [COMMIT
2bd90 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  ] is converted i
2bda0 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d  nto a [ROLLBACK]
2bdb0 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63  ..** The rollbac
2bdc0 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65  k hook is invoke
2bdd0 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20  d on a rollback 
2bde0 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f  that results fro
2bdf0 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f  m a commit.** ho
2be00 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e  ok returning non
2be10 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69  -zero, just as i
2be20 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20  t would be with 
2be30 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61  any other rollba
2be40 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ck..**.** For th
2be50 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
2be60 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
2be70 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
2be80 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f   have been.** ro
2be90 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
2bea0 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
2beb0 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
2bec0 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
2bed0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
2bee0 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
2bef0 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
2bf00 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a  ack to occur..**
2bf10 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61   The rollback ca
2bf20 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
2bf30 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
2bf40 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
2bf50 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2bf60 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
2bf70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2bf80 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
2bf90 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63  ..** The rollbac
2bfa0 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
2bfb0 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
2bfc0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
2bfd0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
2bfe0 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61  ause a commit ca
2bff0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20  llback returned 
2c000 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f  non-zero..** <to
2c010 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69  do> Check on thi
2c020 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  s </todo>.**.** 
2c030 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
2c040 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2c050 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  k()] interface..
2c060 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
2c070 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 35 31 5d 20  ts:.** [H12951] 
2c080 5b 48 31 32 39 35 32 5d 20 5b 48 31 32 39 35 33  [H12952] [H12953
2c090 5d 20 5b 48 31 32 39 35 34 5d 20 5b 48 31 32 39  ] [H12954] [H129
2c0a0 35 35 5d 0a 2a 2a 20 5b 48 31 32 39 36 31 5d 20  55].** [H12961] 
2c0b0 5b 48 31 32 39 36 32 5d 20 5b 48 31 32 39 36 33  [H12962] [H12963
2c0c0 5d 20 5b 48 31 32 39 36 34 5d 0a 2a 2f 0a 76 6f  ] [H12964].*/.vo
2c0d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  id *sqlite3_comm
2c0e0 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  it_hook(sqlite3*
2c0f0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
2c100 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
2c110 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2c120 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76  hook(sqlite3*, v
2c130 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20  oid(*)(void *), 
2c140 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
2c150 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68  API3REF: Data Ch
2c160 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f  ange Notificatio
2c170 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  n Callbacks {H12
2c180 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a  970} <S60400>.**
2c190 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2c1a0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e  update_hook() in
2c1b0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2c1c0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
2c1d0 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
2c1e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2c1f0 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69  ection] identifi
2c200 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2c210 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62  argument.** to b
2c220 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2c230 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
2c240 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
2c250 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79   deleted..** Any
2c260 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2c270 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2c280 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
2c290 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  n.** for the sam
2c2a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2c2b0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
2c2c0 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  den..**.** The s
2c2d0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2c2e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2c2f0 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69  he function to i
2c300 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20  nvoke when a.** 
2c310 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
2c320 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
2c330 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ted..** The firs
2c340 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2c350 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
2c360 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
2c370 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
2c380 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
2c390 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73  hook()..** The s
2c3a0 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61  econd callback a
2c3b0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
2c3c0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
2c3d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
2c3e0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
2c3f0 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e  E_UPDATE], depen
2c400 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
2c410 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
2c420 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  d the callback.*
2c430 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  * to be invoked.
2c440 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e  .** The third an
2c450 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  d fourth argumen
2c460 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ts to the callba
2c470 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74  ck contain point
2c480 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ers to the.** da
2c490 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65  tabase and table
2c4a0 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67   name containing
2c4b0 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f   the affected ro
2c4c0 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20  w..** The final 
2c4d0 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
2c4e0 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
2c4f0 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
2c500 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   In the case of 
2c510 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
2c520 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
2c530 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
2c540 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
2c550 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  ** The update ho
2c560 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
2c570 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2c580 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
2c590 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
2c5a0 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
2c5b0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
2c5c0 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 6e  uence)..**.** In
2c5d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
2c5e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65  lementation, the
2c5f0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
2c600 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
2c610 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20  hen duplication 
2c620 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
2c630 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a   because of an.*
2c640 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c  * [ON CONFLICT |
2c650 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50   ON CONFLICT REP
2c660 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 4e  LACE] clause.  N
2c670 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74 65  or is the update
2c680 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64   hook.** invoked
2c690 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64   when rows are d
2c6a0 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 65  eleted using the
2c6b0 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
2c6c0 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  ization]..** The
2c6d0 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69   exceptions defi
2c6e0 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 61  ned in this para
2c6f0 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e  graph might chan
2c700 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
2c710 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
2c720 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ite..**.** The u
2c730 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65  pdate hook imple
2c740 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e  mentation must n
2c750 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
2c760 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
2c770 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2c780 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2c790 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61  invoked the upda
2c7a0 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63  te hook.  Any ac
2c7b0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
2c7c0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2c7d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2c7e0 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
2c7f0 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
2c800 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
2c810 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c820 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
2c830 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65  gered the update
2c840 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74   hook..** Note t
2c850 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
2c860 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
2c870 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c880 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
2c890 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
2c8a0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
2c8b0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
2c8c0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
2c8d0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49  ragraph..**.** I
2c8e0 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
2c8f0 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
2c900 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
2c910 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20  s pArg value.** 
2c920 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
2c930 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
2c940 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2c950 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
2c960 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2c970 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  k()] and [sqlite
2c980 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2c990 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  )].** interfaces
2c9a0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
2c9b0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31  ents:.** [H12971
2c9c0 5d 20 5b 48 31 32 39 37 33 5d 20 5b 48 31 32 39  ] [H12973] [H129
2c9d0 37 35 5d 20 5b 48 31 32 39 37 37 5d 20 5b 48 31  75] [H12977] [H1
2c9e0 32 39 37 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b  2979] [H12981] [
2c9f0 48 31 32 39 38 33 5d 20 5b 48 31 32 39 38 36 5d  H12983] [H12986]
2ca00 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2ca10 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
2ca20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2ca30 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
2ca40 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
2ca50 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
2ca60 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
2ca70 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
2ca80 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
2ca90 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
2caa0 20 50 61 67 65 72 20 43 61 63 68 65 20 7b 48 31   Pager Cache {H1
2cab0 30 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a  0330} <S30900>.*
2cac0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
2cad0 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
2cae0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
2caf0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
2cb00 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
2cb10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
2cb20 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
2cb30 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
2cb40 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
2cb50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
2cb60 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
2cb70 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
2cb80 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
2cb90 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
2cba0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
2cbb0 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
2cbc0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2cbd0 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a  t is false..**.*
2cbe0 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20  * Cache sharing 
2cbf0 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
2cc00 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
2cc10 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
2cc20 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
2cc30 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
2cc40 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
2cc50 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
2cc60 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
2cc70 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
2cc80 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
2cc90 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
2cca0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2ccb0 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69   The cache shari
2ccc0 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74  ng mode set by t
2ccd0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66  his interface ef
2cce0 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71  fects all subseq
2ccf0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
2cd00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2cd10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2cd20 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  _v2()], and [sql
2cd30 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
2cd40 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61  ** Existing data
2cd50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2cd60 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68   continue use th
2cd70 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a  e sharing mode.*
2cd80 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66  * that was in ef
2cd90 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65  fect at the time
2cda0 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65   they were opene
2cdb0 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  d..**.** Virtual
2cdc0 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62   tables cannot b
2cdd0 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68  e used with a sh
2cde0 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68 65  ared cache.  Whe
2cdf0 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  n shared.** cach
2ce00 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68  e is enabled, th
2ce10 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2ce20 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20  e_module()] API 
2ce30 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
2ce40 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
2ce50 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  es will always r
2ce60 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a  eturn an error..
2ce70 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2ce80 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
2ce90 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64  TE_OK] if shared
2cea0 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c   cache was enabl
2ceb0 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
2cec0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2ced0 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   An [error code]
2cee0 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68   is returned oth
2cef0 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68  erwise..**.** Sh
2cf00 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
2cf10 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
2cf20 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  t. But this migh
2cf30 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
2cf40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
2cf50 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
2cf60 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
2cf70 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
2cf80 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
2cf90 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
2cfa0 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  plicitly..**.** 
2cfb0 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69  See Also:  [SQLi
2cfc0 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20  te Shared-Cache 
2cfd0 4d 6f 64 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71 75  Mode].**.** Requ
2cfe0 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 33 33  irements: [H1033
2cff0 31 5d 20 5b 48 31 30 33 33 36 5d 20 5b 48 31 30  1] [H10336] [H10
2d000 33 33 37 5d 20 5b 48 31 30 33 33 39 5d 0a 2a 2f  337] [H10339].*/
2d010 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
2d020 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
2d030 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2d040 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20  PI3REF: Attempt 
2d050 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d  To Free Heap Mem
2d060 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 33  ory {H17340} <S3
2d070 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0220>.**.** The 
2d080 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2d090 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61  memory() interfa
2d0a0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
2d0b0 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f  ree N bytes.** o
2d0c0 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
2d0d0 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
2d0e0 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
2d0f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a  ry allocations.*
2d100 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  * held by the da
2d110 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20  tabase library. 
2d120 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73  {END}  Memory us
2d130 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
2d140 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f  base.** pages to
2d150 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
2d160 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
2d170 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74  le of non-essent
2d180 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73  ial memory..** s
2d190 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2d1a0 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20  emory() returns 
2d1b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d1c0 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
2d1d0 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67  ed,.** which mig
2d1e0 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
2d1f0 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ss than the amou
2d200 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a  nt requested..**
2d210 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2d220 3a 20 5b 48 31 37 33 34 31 5d 20 5b 48 31 37 33  : [H17341] [H173
2d230 34 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  42].*/.int sqlit
2d240 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2d250 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y(int);../*.** C
2d260 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20  API3REF: Impose 
2d270 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20  A Limit On Heap 
2d280 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c 53  Size {H17350} <S
2d290 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30220>.**.** The
2d2a0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
2d2b0 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72  ap_limit() inter
2d2c0 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22 73  face places a "s
2d2d0 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e  oft" limit.** on
2d2e0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
2d2f0 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
2d300 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
2d310 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49   by SQLite..** I
2d320 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c  f an internal al
2d330 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75  location is requ
2d340 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64  ested that would
2d350 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73   exceed the.** s
2d360 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20  oft heap limit, 
2d370 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2d380 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e  _memory()] is in
2d390 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20  voked one or.** 
2d3a0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72  more times to fr
2d3b0 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65  ee up some space
2d3c0 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f   before the allo
2d3d0 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  cation is perfor
2d3e0 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  med..**.** The l
2d3f0 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
2d400 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69  soft", because i
2d410 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  f [sqlite3_relea
2d420 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20  se_memory()].** 
2d430 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66  cannot free suff
2d440 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f  icient memory to
2d450 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d   prevent the lim
2d460 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78  it from being ex
2d470 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d  ceeded,.** the m
2d480 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
2d490 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68  ed anyway and th
2d4a0 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  e current operat
2d4b0 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a  ion proceeds..**
2d4c0 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f  .** A negative o
2d4d0 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
2d4e0 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
2d4f0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
2d500 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
2d510 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2d520 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
2d530 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2d540 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
2d550 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65  xhausted..** The
2d560 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
2d570 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2d580 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
2d590 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
2d5a0 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2d5b0 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2d5c0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a  ft heap limit..*
2d5d0 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
2d5e0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
2d5f0 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
2d600 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2d610 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2d620 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2d630 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20  fication.  This 
2d640 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74  is why the limit
2d650 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20   is.** called a 
2d660 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49  "soft" limit.  I
2d670 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e  t is advisory on
2d680 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ly..**.** Prior 
2d690 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
2d6a0 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f  n 3.5.0, this ro
2d6b0 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74  utine only const
2d6c0 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72  rained the memor
2d6d0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62  y.** allocated b
2d6e0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
2d6f0 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72  d - the same thr
2d700 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69  ead in which thi
2d710 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e  s routine.** run
2d720 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  s.  Beginning wi
2d730 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
2d740 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66  n 3.5.0, the sof
2d750 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a  t heap limit is.
2d760 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c  ** applied to al
2d770 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76  l threads. The v
2d780 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66  alue specified f
2d790 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2d7a0 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20   limit.** is an 
2d7b0 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74  upper bound on t
2d7c0 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20  he total memory 
2d7d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61  allocation for a
2d7e0 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a  ll threads. In.*
2d7f0 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  * version 3.5.0 
2d800 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68  there is no mech
2d810 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69  anism for limiti
2d820 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67  ng the heap usag
2d830 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64  e for.** individ
2d840 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a  ual threads..**.
2d850 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
2d860 0a 2a 2a 20 5b 48 31 36 33 35 31 5d 20 5b 48 31  .** [H16351] [H1
2d870 36 33 35 32 5d 20 5b 48 31 36 33 35 33 5d 20 5b  6352] [H16353] [
2d880 48 31 36 33 35 34 5d 20 5b 48 31 36 33 35 35 5d  H16354] [H16355]
2d890 20 5b 48 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f 69   [H16358].*/.voi
2d8a0 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  d sqlite3_soft_h
2d8b0 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a  eap_limit(int);.
2d8c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d8d0 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74   Extract Metadat
2d8e0 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e  a About A Column
2d8f0 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 48 31 32   Of A Table {H12
2d900 38 35 30 7d 20 3c 53 36 30 33 30 30 3e 0a 2a 2a  850} <S60300>.**
2d910 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2d920 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74   returns metadat
2d930 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
2d940 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
2d950 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62  pecific.** datab
2d960 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73  ase table access
2d970 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b  ible using the [
2d980 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d990 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70  ion] handle.** p
2d9a0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
2d9b0 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  st function argu
2d9c0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2d9d0 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69  column is identi
2d9e0 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
2d9f0 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f  nd, third and fo
2da00 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
2da10 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  to.** this funct
2da20 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ion. The second 
2da30 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74  parameter is eit
2da40 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  her the name of 
2da50 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2da60 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74  (i.e. "main", "t
2da70 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63  emp" or an attac
2da80 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f  hed database) co
2da90 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65  ntaining the spe
2daa0 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20  cified.** table 
2dab0 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69  or NULL. If it i
2dac0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
2dad0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2dae0 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
2daf0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
2db00 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
2db10 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20   algorithm used 
2db20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
2db30 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  engine to.** res
2db40 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
2db50 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
2db60 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  s..**.** The thi
2db70 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
2db80 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
2db90 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
2dba0 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
2dbb0 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  mn.** name of th
2dbc0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e  e desired column
2dbd0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
2dbe0 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65  Neither of these
2dbf0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d   parameters.** m
2dc00 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ay be NULL..**.*
2dc10 2a 20 4d 65 74 61 64 61 74 61 20 69 73 20 72 65  * Metadata is re
2dc20 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e  turned by writin
2dc30 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20  g to the memory 
2dc40 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64  locations passed
2dc50 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61   as the 5th.** a
2dc60 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61  nd subsequent pa
2dc70 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
2dc80 20 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f   function. Any o
2dc90 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74  f these argument
2dca0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c  s may be.** NULL
2dcb0 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
2dcc0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2dcd0 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
2dce0 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64  adata is omitted
2dcf0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
2dd00 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2dd10 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2dd20 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72  r><th> Parameter
2dd30 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e   <th> Output<br>
2dd40 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72  Type <th>  Descr
2dd50 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  iption.**.** <tr
2dd60 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63  ><td> 5th <td> c
2dd70 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2dd80 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72  Data type.** <tr
2dd90 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63  ><td> 6th <td> c
2dda0 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2ddb0 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20  Name of default 
2ddc0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2ddd0 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37  ce.** <tr><td> 7
2dde0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2ddf0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2de00 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
2de10 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
2de20 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74  t.** <tr><td> 8t
2de30 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2de40 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2de50 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
2de60 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
2de70 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74  Y.** <tr><td> 9t
2de80 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2de90 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2dea0 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49  column is [AUTOI
2deb0 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74  NCREMENT].** </t
2dec0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2ded0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
2dee0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
2def0 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
2df00 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
2df10 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  urned for the.**
2df20 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
2df30 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
2df40 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
2df50 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
2df60 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
2df70 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20   any SQLite API 
2df80 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2df90 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2dfa0 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c   table is actual
2dfb0 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65  ly a view, an [e
2dfc0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2dfd0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
2dfe0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
2dff0 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
2e000 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
2e010 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b  id_" and an.** [
2e020 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
2e030 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20  KEY] column has 
2e040 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
2e050 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
2e060 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2e070 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2e080 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
2e090 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
2e0a0 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20  mn. If there is 
2e0b0 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79  no.** explicitly
2e0c0 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47   declared [INTEG
2e0d0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
2e0e0 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65  column, then the
2e0f0 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
2e100 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
2e110 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
2e120 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
2e130 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
2e140 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
2e150 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
2e160 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
2e170 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
2e180 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
2e190 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
2e1a0 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
2e1b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
2e1c0 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
2e1d0 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
2e1e0 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
2e1f0 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
2e200 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2e210 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
2e220 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
2e230 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
2e240 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
2e250 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65   be found, an [e
2e260 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2e270 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
2e280 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74  ror message left
2e290 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61  .** in the [data
2e2a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e2b0 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
2e2c0 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
2e2d0 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a  errmsg())..**.**
2e2e0 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c   This API is onl
2e2f0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2e300 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2e310 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2e320 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2e330 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2e340 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2e350 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
2e360 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2e370 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
2e380 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
2e390 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2e3a0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
2e3b0 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
2e3c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
2e3d0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
2e3e0 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
2e3f0 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
2e400 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
2e410 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
2e420 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
2e430 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
2e440 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
2e450 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
2e460 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
2e470 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
2e480 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
2e490 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ype */.  char co
2e4a0 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c  nst **pzCollSeq,
2e4b0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2e4c0 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  Collation sequen
2e4d0 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74  ce name */.  int
2e4e0 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20   *pNotNull,     
2e4f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2e500 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20  UT: True if NOT 
2e510 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20  NULL constraint 
2e520 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20  exists */.  int 
2e530 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20  *pPrimaryKey,   
2e540 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
2e550 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
2e560 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a  n part of PK */.
2e570 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20    int *pAutoinc 
2e580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e590 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
2e5a0 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d   column is auto-
2e5b0 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a  increment */.);.
2e5c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e5d0 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
2e5e0 6f 6e 20 7b 48 31 32 36 30 30 7d 20 3c 53 32 30  on {H12600} <S20
2e5f0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  500>.**.** This 
2e600 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20  interface loads 
2e610 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  an SQLite extens
2e620 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d  ion library from
2e630 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e   the named file.
2e640 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 31 7d 20  .**.** {H12601} 
2e650 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
2e660 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
2e670 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2e680 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 20  to load an.**   
2e690 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 65 78         SQLite ex
2e6a0 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
2e6b0 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
2e6c0 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a   file zFile..**.
2e6d0 2a 2a 20 7b 48 31 32 36 30 32 7d 20 54 68 65 20  ** {H12602} The 
2e6e0 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a  entry point is z
2e6f0 50 72 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  Proc..**.** {H12
2e700 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62  603} zProc may b
2e710 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61  e 0, in which ca
2e720 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  se the name of t
2e730 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a  he entry point.*
2e740 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
2e750 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  lts to "sqlite3_
2e760 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
2e770 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 34 7d 20  .**.** {H12604} 
2e780 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
2e790 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
2e7a0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74  erface shall ret
2e7b0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
2e7c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2e7d0 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49  uccess and [SQLI
2e7e0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d  TE_ERROR] if som
2e7f0 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ething goes wron
2e800 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 35  g..**.** {H12605
2e810 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  } If an error oc
2e820 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73  curs and pzErrMs
2e830 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e  g is not 0, then
2e840 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2e850 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
2e860 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
2e870 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65  rface shall atte
2e880 6d 70 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  mpt to.**       
2e890 20 20 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73     fill *pzErrMs
2e8a0 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73  g with error mes
2e8b0 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64  sage text stored
2e8c0 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20   in memory.**   
2e8d0 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20         obtained 
2e8e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2e8f0 6c 6c 6f 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 20  lloc()]. {END}  
2e900 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
2e910 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2e920 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69   should free thi
2e930 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c  s memory by call
2e940 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
2e950 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
2e960 36 30 36 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c  606} Extension l
2e970 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65  oading must be e
2e980 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nabled using.** 
2e990 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2e9a0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2e9b0 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72  tension()] prior
2e9c0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   to calling this
2e9d0 20 41 50 49 2c 0a 2a 2a 20 20 20 20 20 20 20 20   API,.**        
2e9e0 20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65    otherwise an e
2e9f0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74  rror will be ret
2ea00 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  urned..**.** See
2ea10 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f   also the [load_
2ea20 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20  extension() SQL 
2ea30 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e  function]..*/.in
2ea40 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  t sqlite3_load_e
2ea50 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69  xtension(.  sqli
2ea60 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2ea70 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78    /* Load the ex
2ea80 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69  tension into thi
2ea90 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  s database conne
2eaa0 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  ction */.  const
2eab0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20   char *zFile,   
2eac0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
2ead0 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63  shared library c
2eae0 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73  ontaining extens
2eaf0 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
2eb00 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f  har *zProc,    /
2eb10 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20  * Entry point.  
2eb20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69  Derived from zFi
2eb30 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61  le if 0 */.  cha
2eb40 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20  r **pzErrMsg    
2eb50 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20     /* Put error 
2eb60 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20  message here if 
2eb70 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  not 0 */.);../*.
2eb80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
2eb90 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
2eba0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
2ebb0 20 7b 48 31 32 36 32 30 7d 20 3c 53 32 30 35 30   {H12620} <S2050
2ebc0 30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e  0>.**.** So as n
2ebd0 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72  ot to open secur
2ebe0 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64  ity holes in old
2ebf0 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  er applications 
2ec00 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72  that are.** unpr
2ec10 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77  epared to deal w
2ec20 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  ith extension lo
2ec30 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20  ading, and as a 
2ec40 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69  means of disabli
2ec50 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20  ng.** extension 
2ec60 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76  loading while ev
2ec70 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e  aluating user-en
2ec80 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66  tered SQL, the f
2ec90 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
2eca0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74  is provided to t
2ecb0 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
2ecc0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2ecd0 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20  )] mechanism on 
2ece0 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 45  and off..**.** E
2ecf0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
2ed00 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75   is off by defau
2ed10 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23  lt. See ticket #
2ed20 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  1863..**.** {H12
2ed30 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73 71  621} Call the sq
2ed40 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
2ed50 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f  d_extension() ro
2ed60 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66  utine with onoff
2ed70 3d 3d 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ==1.**          
2ed80 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
2ed90 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64  n loading on and
2eda0 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e   call it with on
2edb0 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a  off==0 to turn.*
2edc0 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 62 61  *          it ba
2edd0 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2a  ck off again..**
2ede0 0a 2a 2a 20 7b 48 31 32 36 32 32 7d 20 45 78 74  .** {H12622} Ext
2edf0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69  ension loading i
2ee00 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74  s off by default
2ee10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ee20 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
2ee30 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
2ee40 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
2ee50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ee60 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
2ee70 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
2ee80 73 20 7b 48 31 32 36 34 30 7d 20 3c 53 32 30 35  s {H12640} <S205
2ee90 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  00>.**.** This A
2eea0 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65  PI can be invoke
2eeb0 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61  d at program sta
2eec0 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f  rtup in order to
2eed0 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65   register.** one
2eee0 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61   or more statica
2eef0 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e  lly linked exten
2ef00 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20  sions that will 
2ef10 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  be available.** 
2ef20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61  to all new [data
2ef30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2ef40 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  ]. {END}.**.** T
2ef50 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
2ef60 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
2ef70 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
2ef80 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69   an array that i
2ef90 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72  s.** obtained fr
2efa0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2efb0 6f 63 28 29 5d 2e 20 20 49 66 20 79 6f 75 20 72  oc()].  If you r
2efc0 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  un a memory leak
2efd0 20 63 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e 20 79   checker.** on y
2efe0 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20  our program and 
2eff0 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61  it reports a lea
2f000 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 69  k because of thi
2f010 73 20 61 72 72 61 79 2c 20 69 6e 76 6f 6b 65 0a  s array, invoke.
2f020 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2f030 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
2f040 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 73 68 75  ()] prior to shu
2f050 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68  tdown to free th
2f060 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  e memory..**.** 
2f070 7b 48 31 32 36 34 31 7d 20 54 68 69 73 20 66 75  {H12641} This fu
2f080 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 73  nction registers
2f090 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e   an extension en
2f0a0 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69  try point that i
2f0b0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75  s.**          au
2f0c0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f  tomatically invo
2f0d0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e  ked whenever a n
2f0e0 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ew [database con
2f0f0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20  nection].**     
2f100 20 20 20 20 20 69 73 20 6f 70 65 6e 65 64 20 75       is opened u
2f110 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  sing [sqlite3_op
2f120 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2f130 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
2f140 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
2f150 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a  e3_open_v2()]..*
2f160 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 7d 20 44 75  *.** {H12642} Du
2f170 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f  plicate extensio
2f180 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20  ns are detected 
2f190 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  so calling this 
2f1a0 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20  routine.**      
2f1b0 20 20 20 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d      multiple tim
2f1c0 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
2f1d0 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61   extension is ha
2f1e0 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rmless..**.** {H
2f1f0 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f 75 74  12643} This rout
2f200 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69  ine stores a poi
2f210 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 65  nter to the exte
2f220 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 61  nsion in an arra
2f230 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  y.**          th
2f240 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66  at is obtained f
2f250 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2f260 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  loc()]..**.** {H
2f270 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63  12644} Automatic
2f280 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c   extensions appl
2f290 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72  y across all thr
2f2a0 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  eads..*/.int sql
2f2b0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
2f2c0 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72  ion(void (*xEntr
2f2d0 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a  yPoint)(void));.
2f2e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f2f0 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63   Reset Automatic
2f300 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
2f310 6e 67 20 7b 48 31 32 36 36 30 7d 20 3c 53 32 30  ng {H12660} <S20
2f320 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  500>.**.** This 
2f330 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
2f340 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79  s all previously
2f350 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f   registered auto
2f360 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69  matic.** extensi
2f370 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74 20 75  ons. {END}  It u
2f380 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
2f390 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a   of all prior.**
2f3a0 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65   [sqlite3_auto_e
2f3b0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c  xtension()] call
2f3c0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 36 31  s..**.** {H12661
2f3d0 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  } This function 
2f3e0 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65  disables all pre
2f3f0 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
2f400 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ed.**          a
2f410 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
2f420 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  ons..**.** {H126
2f430 36 32 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f  62} This functio
2f440 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d  n disables autom
2f450 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20  atic extensions 
2f460 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a  in all threads..
2f470 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2f480 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
2f490 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  sion(void);../*.
2f4a0 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ****** EXPERIMEN
2f4b0 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f  TAL - subject to
2f4c0 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20   change without 
2f4d0 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  notice *********
2f4e0 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20  *****.**.** The 
2f4f0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
2f500 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
2f510 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72  echanism is curr
2f520 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
2f530 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
2f540 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
2f550 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
2f560 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
2f570 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
2f580 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
2f590 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
2f5a0 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
2f5b0 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
2f5c0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
2f5d0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
2f5e0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
2f5f0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
2f600 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
2f610 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
2f620 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
2f630 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
2f640 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
2f650 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75  /../*.** Structu
2f660 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20  res used by the 
2f670 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
2f680 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64  terface.*/.typed
2f690 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2f6a0 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76  3_vtab sqlite3_v
2f6b0 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72  tab;.typedef str
2f6c0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
2f6d0 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69  x_info sqlite3_i
2f6e0 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64  ndex_info;.typed
2f6f0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2f700 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71  3_vtab_cursor sq
2f710 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2f720 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  r;.typedef struc
2f730 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
2f740 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b   sqlite3_module;
2f750 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f760 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
2f770 4f 62 6a 65 63 74 20 7b 48 31 38 30 30 30 7d 20  Object {H18000} 
2f780 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20400>.** KEYW
2f790 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f  ORDS: sqlite3_mo
2f7a0 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61  dule {virtual ta
2f7b0 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45  ble module}.** E
2f7c0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
2f7d0 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65  * This structure
2f7e0 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c  , sometimes call
2f7f0 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20  ed a a "virtual 
2f800 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a  table module", .
2f810 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ** defines the i
2f820 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2f830 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
2f840 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73  es].  .** This s
2f850 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74  tructure consist
2f860 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68  s mostly of meth
2f870 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
2f880 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74  le..**.** A virt
2f890 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
2f8a0 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66   is created by f
2f8b0 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73  illing in a pers
2f8c0 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e  istent.** instan
2f8d0 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
2f8e0 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67  ture and passing
2f8f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2f900 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74  at instance.** t
2f910 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2f920 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b  e_module()] or [
2f930 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
2f940 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  odule_v2()]..** 
2f950 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e  The registration
2f960 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75   remains valid u
2f970 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61  ntil it is repla
2f980 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65  ced by a differe
2f990 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20  nt.** module or 
2f9a0 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62  until the [datab
2f9b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2f9c0 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e  closes.  The con
2f9d0 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20  tent.** of this 
2f9e0 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e  structure must n
2f9f0 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20  ot change while 
2fa00 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64  it is registered
2fa10 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74   with.** any dat
2fa20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2fa30 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
2fa40 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69  te3_module {.  i
2fa50 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
2fa60 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71  nt (*xCreate)(sq
2fa70 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
2fa80 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
2fa90 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
2faa0 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
2fab0 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
2fac0 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
2fad0 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
2fae0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e  *);.  int (*xCon
2faf0 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20  nect)(sqlite3*, 
2fb00 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
2fb10 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
2fb20 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
2fb30 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
2fb40 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
2fb50 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
2fb60 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
2fb70 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28  t (*xBestIndex)(
2fb80 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2fb90 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64  Tab, sqlite3_ind
2fba0 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74  ex_info*);.  int
2fbb0 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28   (*xDisconnect)(
2fbc0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2fbd0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  Tab);.  int (*xD
2fbe0 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f  estroy)(sqlite3_
2fbf0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
2fc00 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
2fc10 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2fc20 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  , sqlite3_vtab_c
2fc30 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72  ursor **ppCursor
2fc40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  );.  int (*xClos
2fc50 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e)(sqlite3_vtab_
2fc60 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
2fc70 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74  (*xFilter)(sqlit
2fc80 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
2fc90 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e   int idxNum, con
2fca0 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c  st char *idxStr,
2fcb0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2fcc0 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74   int argc, sqlit
2fcd0 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29  e3_value **argv)
2fce0 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29  ;.  int (*xNext)
2fcf0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
2fd00 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
2fd10 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74  xEof)(sqlite3_vt
2fd20 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
2fd30 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71  nt (*xColumn)(sq
2fd40 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2fd50 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r*, sqlite3_cont
2fd60 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ext*, int);.  in
2fd70 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69  t (*xRowid)(sqli
2fd80 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2fd90 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
2fda0 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20  *pRowid);.  int 
2fdb0 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74  (*xUpdate)(sqlit
2fdc0 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20  e3_vtab *, int, 
2fdd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
2fde0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
2fdf0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67  *);.  int (*xBeg
2fe00 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  in)(sqlite3_vtab
2fe10 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
2fe20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
2fe30 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
2fe40 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28   int (*xCommit)(
2fe50 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2fe60 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  Tab);.  int (*xR
2fe70 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33  ollback)(sqlite3
2fe80 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
2fe90 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63   int (*xFindFunc
2fea0 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  tion)(sqlite3_vt
2feb0 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e  ab *pVtab, int n
2fec0 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Arg, const char 
2fed0 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20  *zName,.        
2fee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2fef0 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73  oid (**pxFunc)(s
2ff00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2ff10 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2ff20 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20  e**),.          
2ff30 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
2ff40 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e  d **ppArg);.  in
2ff50 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c  t (*xRename)(sql
2ff60 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
2ff70 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2ff80 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ew);.};../*.** C
2ff90 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
2ffa0 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20   Table Indexing 
2ffb0 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 31 38  Information {H18
2ffc0 31 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a  100} <S20400>.**
2ffd0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
2ffe0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a  e3_index_info.**
2fff0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
30000 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30010 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
30020 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62  ture and its sub
30030 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73  structures is us
30040 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e  ed to.** pass in
30050 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61  formation into a
30060 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72  nd receive the r
30070 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78  eply from the [x
30080 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65  BestIndex].** me
30090 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75  thod of a [virtu
300a0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
300b0 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e  .  The fields un
300c0 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61  der **Inputs** a
300d0 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73  re the.** inputs
300e0 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61   to xBestIndex a
300f0 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79  nd are read-only
30100 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e  .  xBestIndex in
30110 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73  serts its.** res
30120 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a  ults into the **
30130 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73  Outputs** fields
30140 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f 6e  ..**.** The aCon
30150 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
30160 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
30170 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
30180 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a   of the form:.**
30190 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20  .** <pre>column 
301a0 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a  OP expr</pre>.**
301b0 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20  .** where OP is 
301c0 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20  =, &lt;, &lt;=, 
301d0 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 20  &gt;, or &gt;=. 
301e0 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   The particular 
301f0 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73  operator is.** s
30200 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72  tored in aConstr
30210 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20  aint[].op.  The 
30220 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
30230 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e  umn is stored in
30240 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  .** aConstraint[
30250 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e  ].iColumn.  aCon
30260 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65  straint[].usable
30270 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a   is TRUE if the.
30280 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72  ** expr on the r
30290 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63  ight-hand side c
302a0 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  an be evaluated 
302b0 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f  (and thus the co
302c0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75  nstraint.** is u
302d0 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65  sable) and false
302e0 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a   if it cannot..*
302f0 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a  *.** The optimiz
30300 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  er automatically
30310 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f   inverts terms o
30320 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72  f the form "expr
30330 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61   OP column".** a
30340 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73  nd makes other s
30350 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74  implifications t
30360 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  o the WHERE clau
30370 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74  se in an attempt
30380 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61   to.** get as ma
30390 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ny WHERE clause 
303a0 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66  terms into the f
303b0 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  orm shown above 
303c0 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20  as possible..** 
303d0 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
303e0 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70  ] array only rep
303f0 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73  orts WHERE claus
30400 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63  e terms in the c
30410 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74  orrect.** form t
30420 68 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 65  hat refer to the
30430 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74   particular virt
30440 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20  ual table being 
30450 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  queried..**.** I
30460 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
30470 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
30480 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69  ause is stored i
30490 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a  n aOrderBy[]..**
304a0 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f   Each term of aO
304b0 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61  rderBy records a
304c0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f   column of the O
304d0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a  RDER BY clause..
304e0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74  **.** The [xBest
304f0 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75  Index] method mu
30500 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61  st fill aConstra
30510 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20  intUsage[] with 
30520 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
30530 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65  bout what parame
30540 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20  ters to pass to 
30550 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61 72 67  xFilter.  If arg
30560 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a  vIndex>0 then.**
30570 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20   the right-hand 
30580 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72  side of the corr
30590 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74  esponding aConst
305a0 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75  raint[] is evalu
305b0 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f  ated.** and beco
305c0 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65  mes the argvInde
305d0 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72  x-th entry in ar
305e0 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74 72 61  gv.  If aConstra
305f0 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a  intUsage[].omit.
30600 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e  ** is true, then
30610 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
30620 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65  is assumed to be
30630 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62   fully handled b
30640 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c  y the.** virtual
30650 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f   table and is no
30660 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20  t checked again 
30670 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  by SQLite..**.**
30680 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20   The idxNum and 
30690 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72  idxPtr values ar
306a0 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70  e recorded and p
306b0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a  assed into the.*
306c0 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68  * [xFilter] meth
306d0 6f 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  od..** [sqlite3_
306e0 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20  free()] is used 
306f0 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69  to free idxPtr i
30700 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 66 0a 2a  f and only iff.*
30710 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50  * needToFreeIdxP
30720 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a  tr is true..**.*
30730 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e  * The orderByCon
30740 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74  sumed means that
30750 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46   output from [xF
30760 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77  ilter]/[xNext] w
30770 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20  ill occur in.** 
30780 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65  the correct orde
30790 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65  r to satisfy the
307a0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
307b0 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61   so that no sepa
307c0 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20  rate.** sorting 
307d0 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64  step is required
307e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69  ..**.** The esti
307f0 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
30800 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
30810 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
30820 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
30830 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
30840 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
30850 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
30860 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
30870 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
30880 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
30890 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
308a0 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
308b0 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
308c0 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
308d0 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
308e0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
308f0 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
30900 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
30910 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
30920 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
30930 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
30940 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
30950 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
30960 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
30970 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
30980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
30990 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
309a0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
309b0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
309c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
309d0 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
309e0 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
309f0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
30a00 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
30a10 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
30a20 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
30a30 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
30a40 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
30a50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
30a60 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
30a70 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
30a80 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
30a90 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
30aa0 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
30ab0 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
30ac0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
30ad0 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
30ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
30af0 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
30b00 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
30b10 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
30b20 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
30b30 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
30b40 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
30b50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
30b60 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
30b70 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
30b80 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
30b90 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
30ba0 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
30bb0 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
30bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
30bd0 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
30be0 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75  lause */.  /* Ou
30bf0 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
30c00 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
30c10 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
30c20 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
30c30 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
30c40 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
30c50 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
30c60 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
30c70 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
30c80 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
30c90 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
30ca0 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
30cb0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
30cc0 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
30cd0 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
30ce0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
30cf0 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
30d00 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
30d10 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
30d20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
30d30 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
30d40 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
30d50 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
30d60 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
30d70 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
30d80 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
30d90 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
30da0 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
30db0 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
30dc0 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
30dd0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
30de0 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
30df0 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
30e00 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
30e10 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
30e20 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
30e30 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
30e40 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .};.#define SQLI
30e50 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
30e60 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
30e70 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
30e80 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
30e90 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
30ea0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
30eb0 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
30ec0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
30ed0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
30ee0 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
30ef0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
30f00 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
30f10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
30f20 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
30f30 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41  TCH 64../*.** CA
30f40 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
30f50 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
30f60 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   Implementation 
30f70 7b 48 31 38 32 30 30 7d 20 3c 53 32 30 34 30 30  {H18200} <S20400
30f80 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
30f90 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  L.**.** This rou
30fa0 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20  tine is used to 
30fb0 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b  register a new [
30fc0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
30fd0 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 4d  dule] name..** M
30fe0 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74  odule names must
30ff0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62   be registered b
31000 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e  efore.** creatin
31010 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c  g a new [virtual
31020 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68   table] using th
31030 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66  e module, or bef
31040 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70  ore using a.** p
31050 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74  reexisting [virt
31060 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74  ual table] for t
31070 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a  he module..**.**
31080 20 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65   The module name
31090 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 6f   is registered o
310a0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
310b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
310c0 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
310d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
310e0 20 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68    The name of th
310f0 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65  e module is give
31100 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63  n by the .** sec
31110 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
31120 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
31130 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
31140 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65   to.** the imple
31150 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
31160 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
31170 6d 6f 64 75 6c 65 5d 2e 20 20 20 54 68 65 20 66  module].   The f
31180 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74  ourth.** paramet
31190 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
311a0 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70  ry client data p
311b0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
311c0 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a  assed through.**
311d0 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61   into the [xCrea
311e0 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63  te] and [xConnec
311f0 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68  t] methods of th
31200 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
31210 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61  module.** when a
31220 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62   new virtual tab
31230 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63  le is be being c
31240 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74  reated or reinit
31250 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  ialized..**.** T
31260 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 68 61  his interface ha
31270 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
31280 6d 65 20 65 66 66 65 63 74 20 61 73 20 63 61 6c  me effect as cal
31290 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ling.** [sqlite3
312a0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
312b0 32 28 29 5d 20 77 69 74 68 20 61 20 4e 55 4c 4c  2()] with a NULL
312c0 20 63 6c 69 65 6e 74 20 64 61 74 61 20 64 65 73   client data des
312d0 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c 49  tructor..*/.SQLI
312e0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
312f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
31300 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c  te_module(.  sql
31310 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
31320 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
31330 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
31340 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
31350 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
31360 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
31370 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
31380 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
31390 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
313a0 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65  dule *p,   /* Me
313b0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
313c0 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
313d0 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20  pClientData     
313e0 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
313f0 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
31400 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a  xConnect */.);..
31410 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31420 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75  Register A Virtu
31430 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65  al Table Impleme
31440 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 31 30 7d  ntation {H18210}
31450 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50   <S20400>.** EXP
31460 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
31470 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
31480 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65  identical to the
31490 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
314a0 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 74 68 6f  _module()] metho
314b0 64 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  d,.** except tha
314c0 74 20 69 74 20 68 61 73 20 61 6e 20 65 78 74 72  t it has an extr
314d0 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  a parameter to s
314e0 70 65 63 69 66 79 20 0a 2a 2a 20 61 20 64 65 73  pecify .** a des
314f0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
31500 20 66 6f 72 20 74 68 65 20 63 6c 69 65 6e 74 20   for the client 
31510 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 53  data pointer.  S
31520 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e  QLite will.** in
31530 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
31540 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66  tor function (if
31550 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29   it is not NULL)
31560 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   when SQLite.** 
31570 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20  no longer needs 
31580 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20  the pClientData 
31590 70 6f 69 6e 74 65 72 2e 20 20 0a 2a 2f 0a 53 51  pointer.  .*/.SQ
315a0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
315b0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  L int sqlite3_cr
315c0 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a  eate_module_v2(.
315d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
315e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
315f0 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
31600 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
31610 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
31620 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
31630 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
31640 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
31650 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
31660 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20  e3_module *p,   
31670 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
31680 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
31690 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61  oid *pClientData
316a0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69  ,         /* Cli
316b0 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
316c0 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
316d0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
316e0 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a  y)(void*)     /*
316f0 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74   Module destruct
31700 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29  or function */.)
31710 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31720 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
31730 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74   Instance Object
31740 20 7b 48 31 38 30 31 30 7d 20 3c 53 32 30 34 30   {H18010} <S2040
31750 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
31760 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20  sqlite3_vtab.** 
31770 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
31780 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
31790 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
317a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
317b0 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a  ses a subclass.*
317c0 2a 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * of the followi
317d0 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  ng structure to 
317e0 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69  describe a parti
317f0 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a  cular instance.*
31800 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  * of the [virtua
31810 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20  l table].  Each 
31820 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a  subclass will.**
31830 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20   be tailored to 
31840 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
31850 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ds of the module
31860 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
31870 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20  .** The purpose 
31880 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61  of this supercla
31890 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20  ss is to define 
318a0 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74  certain fields t
318b0 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f  hat are.** commo
318c0 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20  n to all module 
318d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
318e0 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
318f0 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61  ables methods ca
31900 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d  n set an error m
31910 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e  essage by assign
31920 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20  ing a.** string 
31930 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
31940 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
31950 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54  ] to zErrMsg.  T
31960 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  he method should
31970 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68  .** take care th
31980 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72  at any prior str
31990 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20  ing is freed by 
319a0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
319b0 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72  e3_free()].** pr
319c0 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67  ior to assigning
319d0 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f   a new string to
319e0 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72   zErrMsg.  After
319f0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
31a00 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72  ge.** is deliver
31a10 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69  ed up to the cli
31a20 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ent application,
31a30 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
31a40 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
31a50 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71  y.** freed by sq
31a60 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64  lite3_free() and
31a70 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
31a80 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65  ld will be zeroe
31a90 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  d..*/.struct sql
31aa0 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f  ite3_vtab {.  co
31ab0 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
31ac0 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a  le *pModule;  /*
31ad0 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20   The module for 
31ae0 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62  this virtual tab
31af0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  le */.  int nRef
31b00 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
31b10 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f          /* NO LO
31b20 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63  NGER USED */.  c
31b30 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20  har *zErrMsg;   
31b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
31b50 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * Error message 
31b60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
31b70 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56  intf() */.  /* V
31b80 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
31b90 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
31ba0 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
31bb0 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
31bc0 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
31bd0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
31be0 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62   Table Cursor Ob
31bf0 6a 65 63 74 20 20 7b 48 31 38 30 32 30 7d 20 3c  ject  {H18020} <
31c00 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S20400>.** KEYWO
31c10 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
31c20 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61  b_cursor {virtua
31c30 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a  l table cursor}.
31c40 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
31c50 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
31c60 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
31c70 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
31c80 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
31c90 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  s of the.** foll
31ca0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20  owing structure 
31cb0 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73  to describe curs
31cc0 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69  ors that point i
31cd0 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74  nto the.** [virt
31ce0 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61  ual table] and a
31cf0 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
31d00 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
31d10 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
31d20 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
31d30 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
31d40 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
31d50 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d  xOpen | xOpen] m
31d60 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
31d70 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74  ule and are dest
31d80 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  royed.** by the 
31d90 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
31da0 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d  xClose | xClose]
31db0 20 6d 65 74 68 6f 64 2e 20 20 43 75 73 73 6f 72   method.  Cussor
31dc0 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79  s are used.** by
31dd0 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20   the [xFilter], 
31de0 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c  [xNext], [xEof],
31df0 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20   [xColumn], and 
31e00 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73  [xRowid] methods
31e10 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  .** of the modul
31e20 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  e.  Each module 
31e30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
31e40 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68  ill define.** th
31e50 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63  e content of a c
31e60 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20  ursor structure 
31e70 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20  to suit its own 
31e80 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  needs..**.** Thi
31e90 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69  s superclass exi
31ea0 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  sts in order to 
31eb0 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66  define fields of
31ec0 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74   the cursor that
31ed0 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74  .** are common t
31ee0 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61  o all implementa
31ef0 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74  tions..*/.struct
31f00 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
31f10 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33  rsor {.  sqlite3
31f20 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20  _vtab *pVtab;   
31f30 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61     /* Virtual ta
31f40 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73  ble of this curs
31f50 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  or */.  /* Virtu
31f60 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
31f70 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
31f80 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
31f90 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
31fa0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
31fb0 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65  REF: Declare The
31fc0 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72   Schema Of A Vir
31fd0 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38 32  tual Table {H182
31fe0 38 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20  80} <S20400>.** 
31ff0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
32000 2a 2a 20 54 68 65 20 5b 78 43 72 65 61 74 65 5d  ** The [xCreate]
32010 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20   and [xConnect] 
32020 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20  methods of a.** 
32030 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
32040 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73  odule] call this
32050 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
32060 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72   declare the for
32070 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61  mat (the names a
32080 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20  nd datatypes of 
32090 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a  the columns) of.
320a0 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  ** the virtual t
320b0 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65  ables they imple
320c0 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ment..*/.SQLITE_
320d0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
320e0 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65   sqlite3_declare
320f0 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20  _vtab(sqlite3*, 
32100 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c  const char *zSQL
32110 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32120 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46  EF: Overload A F
32130 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69  unction For A Vi
32140 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31 38  rtual Table {H18
32150 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a  300} <S20400>.**
32160 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
32170 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
32180 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61  es can provide a
32190 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65  lternative imple
321a0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75  mentations of fu
321b0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67  nctions.** using
321c0 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74   the [xFindFunct
321d0 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  ion] method of t
321e0 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
321f0 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20  e module].  .** 
32200 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69  But global versi
32210 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e  ons of those fun
32220 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65  ctions.** must e
32230 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  xist in order to
32240 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a   be overloaded..
32250 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d  **.** This API m
32260 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62  akes sure a glob
32270 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20  al version of a 
32280 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
32290 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61  particular.** na
322a0 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66  me and number of
322b0 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73   parameters exis
322c0 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20  ts.  If no such 
322d0 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a  function exists.
322e0 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41  ** before this A
322f0 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20  PI is called, a 
32300 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
32310 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d  created.  The im
32320 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
32330 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  of the new funct
32340 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65  ion always cause
32350 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74  s an exception t
32360 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f  o be thrown.  So
32370 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63  .** the new func
32380 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64  tion is not good
32390 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79   for anything by
323a0 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e   itself.  Its on
323b0 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73  ly.** purpose is
323c0 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f   to be a placeho
323d0 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
323e0 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
323f0 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69  aded.** by a [vi
32400 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f  rtual table]..*/
32410 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
32420 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
32430 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69  _overload_functi
32440 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  on(sqlite3*, con
32450 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61  st char *zFuncNa
32460 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a  me, int nArg);..
32470 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  /*.** The interf
32480 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
32490 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
324a0 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65  sm defined above
324b0 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20   (back up.** to 
324c0 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b  a comment remark
324d0 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20  ably similar to 
324e0 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72  this one) is cur
324f0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
32500 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
32510 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
32520 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
32530 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
32540 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
32550 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
32560 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
32570 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
32580 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
32590 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
325a0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
325b0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
325c0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
325d0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
325e0 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
325f0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
32600 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
32610 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
32620 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49  **.****** EXPERI
32630 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74  MENTAL - subject
32640 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
32650 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a  ut notice ******
32660 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a  ********.*/../*.
32670 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48  ** CAPI3REF: A H
32680 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e  andle To An Open
32690 20 42 4c 4f 42 20 7b 48 31 37 38 30 30 7d 20 3c   BLOB {H17800} <
326a0 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S30230>.** KEYWO
326b0 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  RDS: {BLOB handl
326c0 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  e} {BLOB handles
326d0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
326e0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
326f0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
32700 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68   open BLOB on wh
32710 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
32720 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
32730 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
32740 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  ] can be perform
32750 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f  ed..** Objects o
32760 66 20 74 68 69 73 20 74 79 70 65 20 61 72 65 20  f this type are 
32770 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69  created by [sqli
32780 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
32790 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65  .** and destroye
327a0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
327b0 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20  ob_close()]..** 
327c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
327d0 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73  b_read()] and [s
327e0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
327f0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a  e()] interfaces.
32800 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
32810 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  o read or write 
32820 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e  small subsection
32830 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a  s of the BLOB..*
32840 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * The [sqlite3_b
32850 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
32860 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
32870 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42  he size of the B
32880 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  LOB in bytes..*/
32890 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
328a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
328b0 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
328c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
328d0 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
328e0 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37  emental I/O {H17
328f0 38 31 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  810} <S30230>.**
32900 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
32910 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f  ces opens a [BLO
32920 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c  B handle | handl
32930 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c  e] to the BLOB l
32940 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77  ocated.** in row
32950 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43   iRow, column zC
32960 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61  olumn, table zTa
32970 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20  ble in database 
32980 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72  zDb;.** in other
32990 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65   words, the same
329a0 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64   BLOB that would
329b0 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a   be selected by:
329c0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
329d0 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75      SELECT zColu
329e0 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62  mn FROM zDb.zTab
329f0 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d  le WHERE [rowid]
32a00 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72   = iRow;.** </pr
32a10 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49  e> {END}.**.** I
32a20 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  f the flags para
32a30 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72  meter is non-zer
32a40 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42  o, then the BLOB
32a50 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
32a60 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65  ead.** and write
32a70 20 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 69   access. If it i
32a80 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42  s zero, the BLOB
32a90 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
32aa0 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 49  ead access..** I
32ab0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
32ac0 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75  e to open a colu
32ad0 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20  mn that is part 
32ae0 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70  of an index or p
32af0 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66  rimary .** key f
32b00 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20  or writing. ^If 
32b10 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
32b20 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e  straints] are en
32b30 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a  abled, it is .**
32b40 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
32b50 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74   open a column t
32b60 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  hat is part of a
32b70 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72   [child key] for
32b80 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   writing..**.** 
32b90 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61  Note that the da
32ba0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e  tabase name is n
32bb0 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ot the filename 
32bc0 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  that contains.**
32bd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
32be0 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d  t rather the sym
32bf0 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68  bolic name of th
32c00 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a  e database that.
32c10 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 77  ** is assigned w
32c20 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
32c30 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73   is connected us
32c40 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a  ing [ATTACH]..**
32c50 20 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61   For the main da
32c60 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
32c70 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
32c80 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72  s "main"..** For
32c90 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68   TEMP tables, th
32ca0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
32cb0 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a  is "temp"..**.**
32cc0 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
32cd0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
32ce0 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77  rned and the new
32cf0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
32d00 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20  s written.** to 
32d10 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69  *ppBlob. Otherwi
32d20 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
32d30 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
32d40 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65  nd *ppBlob is se
32d50 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c  t.** to be a nul
32d60 6c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68  l pointer..** Th
32d70 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
32d80 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
32d90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72  onnection] error
32da0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
32db0 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
32dc0 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
32dd0 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
32de0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61  ite3_errmsg()] a
32df0 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75  nd related.** fu
32e00 6e 63 74 69 6f 6e 73 2e 20 20 4e 6f 74 65 20 74  nctions.  Note t
32e10 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20  hat the *ppBlob 
32e20 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61  variable is alwa
32e30 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69  ys initialized i
32e40 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20  n a.** way that 
32e50 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f  makes it safe to
32e60 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
32e70 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f  _blob_close()] o
32e80 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67  n *ppBlob.** reg
32e90 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
32ea0 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
32eb0 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
32ec0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
32ed0 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20  row that a BLOB 
32ee0 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f  handle points to
32ef0 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20   is modified by 
32f00 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20  an.** [UPDATE], 
32f10 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20  [DELETE], or by 
32f20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69  [ON CONFLICT] si
32f30 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68  de-effects.** th
32f40 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  en the BLOB hand
32f50 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20  le is marked as 
32f60 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68  "expired"..** Th
32f70 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e  is is true if an
32f80 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  y column of the 
32f90 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20  row is changed, 
32fa0 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  even a column.**
32fb0 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20   other than the 
32fc0 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e  one the BLOB han
32fd0 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 0a  dle is open on..
32fe0 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** Calls to [sql
32ff0 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
33000 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
33010 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72  lob_write()] for
33020 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c  .** a expired BL
33030 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77  OB handle fail w
33040 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f  ith an return co
33050 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
33060 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e 67 65 73  ORT]..** Changes
33070 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20   written into a 
33080 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68  BLOB prior to th
33090 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20  e BLOB expiring 
330a0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 62  are not.** rollb
330b0 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72  ack by the expir
330c0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f  ation of the BLO
330d0 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73  B.  Such changes
330e0 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
330f0 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68  .** commit if th
33100 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  e transaction co
33110 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
33120 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 73 65  etion..**.** Use
33130 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   the [sqlite3_bl
33140 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
33150 72 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69  rface to determi
33160 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  ne the size of.*
33170 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f  * the opened blo
33180 62 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  b.  The size of 
33190 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62  a blob may not b
331a0 65 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69  e changed by thi
331b0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20  s.** interface. 
331c0 20 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45   Use the [UPDATE
331d0 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f  ] SQL command to
331e0 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65   change the size
331f0 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a   of a.** blob..*
33200 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
33210 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
33220 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
33230 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
33240 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
33250 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69   and the built-i
33260 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c  n [zeroblob] SQL
33270 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65   function can be
33280 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65   used, if desire
33290 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20  d,.** to create 
332a0 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66  an empty, zero-f
332b0 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68  illed blob in wh
332c0 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77  ich to read or w
332d0 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68  rite using.** th
332e0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
332f0 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72  .** To avoid a r
33300 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76  esource leak, ev
33310 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68  ery open [BLOB h
33320 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76  andle] should ev
33330 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72  entually.** be r
33340 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c  eleased by a cal
33350 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
33360 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  ob_close()]..**.
33370 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
33380 0a 2a 2a 20 5b 48 31 37 38 31 33 5d 20 5b 48 31  .** [H17813] [H1
33390 37 38 31 34 5d 20 5b 48 31 37 38 31 36 5d 20 5b  7814] [H17816] [
333a0 48 31 37 38 31 39 5d 20 5b 48 31 37 38 32 31 5d  H17819] [H17821]
333b0 20 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a 69 6e 74   [H17824].*/.int
333c0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70   sqlite3_blob_op
333d0 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  en(.  sqlite3*,.
333e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
333f0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
33400 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74  *zTable,.  const
33410 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a   char *zColumn,.
33420 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
33430 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67  iRow,.  int flag
33440 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f  s,.  sqlite3_blo
33450 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f  b **ppBlob.);../
33460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
33470 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64  lose A BLOB Hand
33480 6c 65 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30  le {H17830} <S30
33490 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65  230>.**.** Close
334a0 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  s an open [BLOB 
334b0 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43  handle]..**.** C
334c0 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68  losing a BLOB sh
334d0 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75  all cause the cu
334e0 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
334f0 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69  n to commit.** i
33500 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f  f there are no o
33510 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70  ther BLOBs, no p
33520 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20  ending prepared 
33530 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20  statements, and 
33540 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
33550 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e  connection is in
33560 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   [autocommit mod
33570 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72  e]..** If any wr
33580 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74  ites were made t
33590 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79  o the BLOB, they
335a0 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69   might be held i
335b0 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c  n cache.** until
335c0 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61   the close opera
335d0 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c  tion if they wil
335e0 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f  l fit..**.** Clo
335f0 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66  sing the BLOB of
33600 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63  ten forces the c
33610 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f  hanges.** out to
33620 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20   disk and so if 
33630 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f  any I/O errors o
33640 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20  ccur, they will 
33650 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20  likely occur.** 
33660 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
33670 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f   the BLOB is clo
33680 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73  sed.  Any errors
33690 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69   that occur duri
336a0 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72  ng.** closing ar
336b0 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20  e reported as a 
336c0 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20  non-zero return 
336d0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
336e0 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20   BLOB is closed 
336f0 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e  unconditionally.
33700 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72    Even if this r
33710 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a  outine returns.*
33720 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c  * an error code,
33730 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69   the BLOB is sti
33740 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  ll closed..**.**
33750 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
33760 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c  utine with a nul
33770 6c 20 70 6f 69 6e 74 65 72 20 28 77 68 69 63 68  l pointer (which
33780 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74   as would be ret
33790 75 72 6e 65 64 0a 2a 2a 20 62 79 20 66 61 69 6c  urned.** by fail
337a0 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ed call to [sqli
337b0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
337c0 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ) is a harmless 
337d0 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  no-op..**.** Req
337e0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
337f0 31 37 38 33 33 5d 20 5b 48 31 37 38 33 36 5d 20  17833] [H17836] 
33800 5b 48 31 37 38 33 39 5d 0a 2a 2f 0a 69 6e 74 20  [H17839].*/.int 
33810 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
33820 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  se(sqlite3_blob 
33830 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
33840 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20  REF: Return The 
33850 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20  Size Of An Open 
33860 42 4c 4f 42 20 7b 48 31 37 38 34 30 7d 20 3c 53  BLOB {H17840} <S
33870 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  30230>.**.** Ret
33880 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e  urns the size in
33890 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
338a0 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  OB accessible vi
338b0 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73  a the .** succes
338c0 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42  sfully opened [B
338d0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69  LOB handle] in i
338e0 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  ts only argument
338f0 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d  .  The.** increm
33900 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72  ental blob I/O r
33910 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79  outines can only
33920 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69   read or overwri
33930 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a  ting existing.**
33940 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74   blob content; t
33950 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67  hey cannot chang
33960 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  e the size of a 
33970 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  blob..**.** This
33980 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f   routine only wo
33990 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68  rks on a [BLOB h
339a0 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73  andle] which has
339b0 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a   been created.**
339c0 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63   by a prior succ
339d0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
339e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
339f0 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68  n()] and which h
33a00 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63  as not.** been c
33a10 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  losed by [sqlite
33a20 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
33a30 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74    Passing any ot
33a40 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a  her pointer in.*
33a50 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  * to this routin
33a60 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  e results in und
33a70 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
33a80 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20  bly undesirable 
33a90 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
33aa0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
33ab0 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a 69 6e 74   [H17843].*/.int
33ac0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79   sqlite3_blob_by
33ad0 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  tes(sqlite3_blob
33ae0 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   *);../*.** CAPI
33af0 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20  3REF: Read Data 
33b00 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72  From A BLOB Incr
33b10 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 35  ementally {H1785
33b20 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a  0} <S30230>.**.*
33b30 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
33b40 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20  is used to read 
33b50 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65  data from an ope
33b60 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  n [BLOB handle] 
33b70 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72  into a.** caller
33b80 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72  -supplied buffer
33b90 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74  . N bytes of dat
33ba0 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  a are copied int
33bb0 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72  o buffer Z.** fr
33bc0 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42  om the open BLOB
33bd0 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
33be0 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
33bf0 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f  .** If offset iO
33c00 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
33c10 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
33c20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
33c30 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
33c40 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
33c50 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
33c60 73 20 72 65 61 64 2e 20 20 49 66 20 4e 20 6f 72  s read.  If N or
33c70 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c   iOffset is.** l
33c80 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b  ess than zero, [
33c90 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
33ca0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
33cb0 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a   data is read..*
33cc0 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68  * The size of th
33cd0 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63  e blob (and henc
33ce0 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61  e the maximum va
33cf0 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74  lue of N+iOffset
33d00 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  ).** can be dete
33d10 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
33d20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
33d30 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
33d40 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65  e..**.** An atte
33d50 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d  mpt to read from
33d60 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f   an expired [BLO
33d70 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20  B handle] fails 
33d80 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  with an.** error
33d90 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
33da0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f  _ABORT]..**.** O
33db0 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54  n success, SQLIT
33dc0 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
33dd0 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20  ..** Otherwise, 
33de0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
33df0 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20  or an [extended 
33e00 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
33e10 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
33e20 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
33e30 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f   works on a [BLO
33e40 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20  B handle] which 
33e50 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64  has been created
33e60 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73  .** by a prior s
33e70 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
33e80 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
33e90 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63  open()] and whic
33ea0 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65  h has not.** bee
33eb0 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c  n closed by [sql
33ec0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
33ed0 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79  )].  Passing any
33ee0 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69   other pointer i
33ef0 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75  n.** to this rou
33f00 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20  tine results in 
33f10 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
33f20 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
33f30 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  le behavior..**.
33f40 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
33f50 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
33f60 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
33f70 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37  rements:.** [H17
33f80 38 35 33 5d 20 5b 48 31 37 38 35 36 5d 20 5b 48  853] [H17856] [H
33f90 31 37 38 35 39 5d 20 5b 48 31 37 38 36 32 5d 20  17859] [H17862] 
33fa0 5b 48 31 37 38 36 33 5d 20 5b 48 31 37 38 36 35  [H17863] [H17865
33fb0 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f 0a 69 6e  ] [H17868].*/.in
33fc0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
33fd0 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ead(sqlite3_blob
33fe0 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74   *, void *Z, int
33ff0 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   N, int iOffset)
34000 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34010 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e  F: Write Data In
34020 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  to A BLOB Increm
34030 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38 37 30 7d  entally {H17870}
34040 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20   <S30230>.**.** 
34050 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
34060 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64   used to write d
34070 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e  ata into an open
34080 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66   [BLOB handle] f
34090 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d  rom a.** caller-
340a0 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
340b0 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   N bytes of data
340c0 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d   are copied from
340d0 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a   the buffer Z.**
340e0 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42   into the open B
340f0 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
34100 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
34110 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 42  .**.** If the [B
34120 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73  LOB handle] pass
34130 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
34140 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74  argument was not
34150 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77   opened for.** w
34160 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
34170 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
34180 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
34190 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a  n()] was zero),.
341a0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
341b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
341c0 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a  _READONLY]..**.*
341d0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
341e0 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20  may only modify 
341f0 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
34200 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a  the BLOB; it is.
34210 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
34220 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20  to increase the 
34230 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75  size of a BLOB u
34240 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a  sing this API..*
34250 2a 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66  * If offset iOff
34260 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
34270 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
34280 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
34290 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
342a0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
342b0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
342c0 77 72 69 74 74 65 6e 2e 20 20 49 66 20 4e 20 69  written.  If N i
342d0 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a  s.** less than z
342e0 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ero [SQLITE_ERRO
342f0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
34300 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
34310 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69  itten..** The si
34320 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28  ze of the BLOB (
34330 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61  and hence the ma
34340 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e  ximum value of N
34350 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e  +iOffset).** can
34360 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
34370 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
34380 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
34390 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
343a0 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77   An attempt to w
343b0 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72  rite to an expir
343c0 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
343d0 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
343e0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  * error code of 
343f0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20  [SQLITE_ABORT]. 
34400 20 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42   Writes to the B
34410 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65  LOB that occurre
34420 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  d.** before the 
34430 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78  [BLOB handle] ex
34440 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f  pired are not ro
34450 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65  lled back by the
34460 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f  .** expiration o
34470 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68  f the handle, th
34480 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
34490 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67  hose changes mig
344a0 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20  ht.** have been 
344b0 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
344c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
344d0 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c  t expired the BL
344e0 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20  OB handle.** or 
344f0 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e  by other indepen
34500 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e  dent statements.
34510 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
34520 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  s, SQLITE_OK is 
34530 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68  returned..** Oth
34540 65 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72  erwise, an  [err
34550 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
34560 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
34570 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
34580 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
34590 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
345a0 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
345b0 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
345c0 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
345d0 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
345e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
345f0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
34600 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
34610 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
34620 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
34630 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
34640 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
34650 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
34660 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
34670 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
34680 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
34690 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
346a0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  vior..**.** See 
346b0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
346c0 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2a 0a  lob_read()]..**.
346d0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
346e0 0a 2a 2a 20 5b 48 31 37 38 37 33 5d 20 5b 48 31  .** [H17873] [H1
346f0 37 38 37 34 5d 20 5b 48 31 37 38 37 35 5d 20 5b  7874] [H17875] [
34700 48 31 37 38 37 36 5d 20 5b 48 31 37 38 37 37 5d  H17876] [H17877]
34710 20 5b 48 31 37 38 37 39 5d 20 5b 48 31 37 38 38   [H17879] [H1788
34720 32 5d 20 5b 48 31 37 38 38 35 5d 0a 2a 2a 20 5b  2] [H17885].** [
34730 48 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e 74 20 73  H17888].*/.int s
34740 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
34750 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
34760 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c  , const void *z,
34770 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66   int n, int iOff
34780 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  set);../*.** CAP
34790 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46  I3REF: Virtual F
347a0 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63  ile System Objec
347b0 74 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 30  ts {H11200} <S20
347c0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72  100>.**.** A vir
347d0 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20  tual filesystem 
347e0 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c  (VFS) is an [sql
347f0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
34800 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
34810 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74  uses to interact
34820 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64  .** with the und
34830 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
34840 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20  g system.  Most 
34850 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f  SQLite builds co
34860 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e  me with a.** sin
34870 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  gle default VFS 
34880 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69  that is appropri
34890 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74  ate for the host
348a0 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65   computer..** Ne
348b0 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72  w VFSes can be r
348c0 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78  egistered and ex
348d0 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e  isting VFSes can
348e0 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64   be unregistered
348f0 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ..** The followi
34900 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ng interfaces ar
34910 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a  e provided..**.*
34920 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66  * The sqlite3_vf
34930 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61  s_find() interfa
34940 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
34950 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69  nter to a VFS gi
34960 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a  ven its name..**
34970 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20   Names are case 
34980 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e 61  sensitive..** Na
34990 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  mes are zero-ter
349a0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
349b0 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 65  rings..** If the
349c0 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20  re is no match, 
349d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
349e0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
349f0 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55  f zVfsName is NU
34a00 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  LL then the defa
34a10 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72  ult VFS is retur
34a20 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56  ned..**.** New V
34a30 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65  FSes are registe
34a40 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33  red with sqlite3
34a50 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e  _vfs_register().
34a60 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53  .** Each new VFS
34a70 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66   becomes the def
34a80 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20  ault VFS if the 
34a90 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73  makeDflt flag is
34aa0 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d   set..** The sam
34ab0 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67  e VFS can be reg
34ac0 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
34ad0 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69   times without i
34ae0 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b  njury..** To mak
34af0 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46  e an existing VF
34b00 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75  S into the defau
34b10 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72  lt VFS, register
34b20 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74   it again.** wit
34b30 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66  h the makeDflt f
34b40 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f  lag set.  If two
34b50 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73   different VFSes
34b60 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d   with the.** sam
34b70 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73  e name are regis
34b80 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76  tered, the behav
34b90 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
34ba0 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69  .  If a.** VFS i
34bb0 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  s registered wit
34bc0 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73  h a name that is
34bd0 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74   NULL or an empt
34be0 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65  y string,.** the
34bf0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
34c00 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
34c10 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20  ** Unregister a 
34c20 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c  VFS with the sql
34c30 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
34c40 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  ter() interface.
34c50 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75  .** If the defau
34c60 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69  lt VFS is unregi
34c70 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20  stered, another 
34c80 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73  VFS is chosen as
34c90 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e  .** the default.
34ca0 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72    The choice for
34cb0 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20   the new VFS is 
34cc0 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  arbitrary..**.**
34cd0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
34ce0 2a 20 5b 48 31 31 32 30 33 5d 20 5b 48 31 31 32  * [H11203] [H112
34cf0 30 36 5d 20 5b 48 31 31 32 30 39 5d 20 5b 48 31  06] [H11209] [H1
34d00 31 32 31 32 5d 20 5b 48 31 31 32 31 35 5d 20 5b  1212] [H11215] [
34d10 48 31 31 32 31 38 5d 0a 2a 2f 0a 73 71 6c 69 74  H11218].*/.sqlit
34d20 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f  e3_vfs *sqlite3_
34d30 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63  vfs_find(const c
34d40 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a  har *zVfsName);.
34d50 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  int sqlite3_vfs_
34d60 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33  register(sqlite3
34d70 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44  _vfs*, int makeD
34d80 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  flt);.int sqlite
34d90 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
34da0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a  (sqlite3_vfs*);.
34db0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34dc0 20 4d 75 74 65 78 65 73 20 7b 48 31 37 30 30 30   Mutexes {H17000
34dd0 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
34de0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
34df0 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74   uses these rout
34e00 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a  ines for thread.
34e10 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69  ** synchronizati
34e20 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20  on. Though they 
34e30 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
34e40 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
34e50 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65   by SQLite, code
34e60 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
34e70 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  nst SQLite is.**
34e80 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73   permitted to us
34e90 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
34ea0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
34eb0 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  he SQLite source
34ec0 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d   code contains m
34ed0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
34ee0 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68  tations.** of th
34ef0 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ese mutex routin
34f00 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69  es.  An appropri
34f10 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ate implementati
34f20 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65  on.** is selecte
34f30 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
34f40 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e  at compile-time.
34f50 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a    The following.
34f60 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
34f70 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  ns are available
34f80 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63   in the SQLite c
34f90 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ore:.**.** <ul>.
34fa0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
34fb0 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c  _MUTEX_OS2.** <l
34fc0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
34fd0 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69  X_PTHREAD.** <li
34fe0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
34ff0 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  _W32.** <li>   S
35000 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50  QLITE_MUTEX_NOOP
35010 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
35020 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  The SQLITE_MUTEX
35030 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61  _NOOP implementa
35040 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66  tion is a set of
35050 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61   routines.** tha
35060 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c  t does no real l
35070 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70  ocking and is ap
35080 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73  propriate for us
35090 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65  e in.** a single
350a0 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
350b0 61 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49  ation.  The SQLI
350c0 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a  TE_MUTEX_OS2,.**
350d0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
350e0 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54  HREAD, and SQLIT
350f0 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c  E_MUTEX_W32 impl
35100 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
35110 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  re appropriate f
35120 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20  or use on OS/2, 
35130 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77  Unix, and Window
35140 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69  s..**.** If SQLi
35150 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
35160 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d  ith the SQLITE_M
35170 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70  UTEX_APPDEF prep
35180 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72  rocessor.** macr
35190 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20  o defined (with 
351a0 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  "-DSQLITE_MUTEX_
351b0 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e  APPDEF=1"), then
351c0 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70   no mutex.** imp
351d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69  lementation is i
351e0 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65  ncluded with the
351f0 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69   library. In thi
35200 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70  s case the.** ap
35210 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
35220 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d  upply a custom m
35230 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
35240 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ion using the.**
35250 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
35260 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66  MUTEX] option of
35270 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   the sqlite3_con
35280 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  fig() function.*
35290 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67  * before calling
352a0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
352b0 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68  ize() or any oth
352c0 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65  er public sqlite
352d0 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  3_.** function t
352e0 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  hat calls sqlite
352f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
35300 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31 7d 20 54  **.** {H17011} T
35310 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
35320 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  _alloc() routine
35330 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77   allocates a new
35340 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65  .** mutex and re
35350 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35360 74 6f 20 69 74 2e 20 7b 48 31 37 30 31 32 7d 20  to it. {H17012} 
35370 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  If it returns NU
35380 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73  LL.** that means
35390 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63 6f   that a mutex co
353a0 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63  uld not be alloc
353b0 61 74 65 64 2e 20 7b 48 31 37 30 31 33 7d 20 53  ated. {H17013} S
353c0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e  QLite.** will un
353d0 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61  wind its stack a
353e0 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  nd return an err
353f0 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20 54 68 65  or. {H17014} The
35400 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
35410 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
35420 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20  loc() is one of 
35430 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  these integer co
35440 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  nstants:.**.** <
35450 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
35460 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a  ITE_MUTEX_FAST.*
35470 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
35480 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
35490 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
354a0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
354b0 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ER.** <li>  SQLI
354c0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
354d0 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  MEM.** <li>  SQL
354e0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
354f0 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _MEM2.** <li>  S
35500 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
35510 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20  IC_PRNG.** <li> 
35520 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
35530 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e  ATIC_LRU.** <li>
35540 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
35550 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f  TATIC_LRU2.** </
35560 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31  ul>.**.** {H1701
35570 35 7d 20 54 68 65 20 66 69 72 73 74 20 74 77 6f  5} The first two
35580 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65   constants cause
35590 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
355a0 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65  lloc() to create
355b0 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e  .** a new mutex.
355c0 20 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20    The new mutex 
355d0 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65  is recursive whe
355e0 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  n SQLITE_MUTEX_R
355f0 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75  ECURSIVE.** is u
35600 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65  sed but not nece
35610 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20  ssarily so when 
35620 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
35630 54 20 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d  T is used. {END}
35640 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d  .** The mutex im
35650 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65  plementation doe
35660 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61  s not need to ma
35670 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e  ke a distinction
35680 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
35690 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
356a0 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  VE and SQLITE_MU
356b0 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64  TEX_FAST if it d
356c0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
356d0 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d 20 42 75  to.  {H17016} Bu
356e0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e  t SQLite will on
356f0 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63  ly request a rec
35700 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a  ursive mutex in.
35710 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69  ** cases where i
35720 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f  t really needs o
35730 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20  ne.  {END} If a 
35740 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72  faster non-recur
35750 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  sive mutex.** im
35760 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
35770 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65  available on the
35780 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20   host platform, 
35790 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73  the mutex subsys
357a0 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74  tem.** might ret
357b0 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78  urn such a mutex
357c0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
357d0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
357e0 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 37  T..**.** {H17017
357f0 7d 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f  } The other allo
35800 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 74  wed parameters t
35810 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
35820 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74  alloc() each ret
35830 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  urn.** a pointer
35840 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65   to a static pre
35850 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20  existing mutex. 
35860 7b 45 4e 44 7d 20 20 53 69 78 20 73 74 61 74 69  {END}  Six stati
35870 63 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a  c mutexes are.**
35880 20 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72   used by the cur
35890 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20  rent version of 
358a0 53 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20  SQLite.  Future 
358b0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
358c0 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64  te.** may add ad
358d0 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20  ditional static 
358e0 6d 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63  mutexes.  Static
358f0 20 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72   mutexes are for
35900 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
35910 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e   by SQLite only.
35920 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
35930 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  hat use SQLite m
35940 75 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a  utexes should.**
35950 20 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79   use only the dy
35960 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65  namic mutexes re
35970 74 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45  turned by SQLITE
35980 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a  _MUTEX_FAST or.*
35990 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  * SQLITE_MUTEX_R
359a0 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20  ECURSIVE..**.** 
359b0 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68  {H17018} Note th
359c0 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65  at if one of the
359d0 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70   dynamic mutex p
359e0 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54  arameters (SQLIT
359f0 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
35a00 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  or SQLITE_MUTEX_
35a10 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73  RECURSIVE) is us
35a20 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ed then sqlite3_
35a30 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a  mutex_alloc().**
35a40 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65   returns a diffe
35a50 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76  rent mutex on ev
35a60 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48 31 37 30  ery call.  {H170
35a70 33 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20  34} But for the 
35a80 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
35a90 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20  types, the same 
35aa0 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65  mutex is returne
35ab0 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20  d on every call 
35ac0 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20  that has.** the 
35ad0 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72  same type number
35ae0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 39 7d  ..**.** {H17019}
35af0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
35b00 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
35b10 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
35b20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
35b30 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
35b40 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 30 7d 20  mutex. {H17020} 
35b50 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75  SQLite is carefu
35b60 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20  l to deallocate 
35b70 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63  every.** dynamic
35b80 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61   mutex that it a
35b90 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31 37 30 32  llocates. {A1702
35ba0 31 7d 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d  1} The dynamic m
35bb0 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20  utexes must not 
35bc0 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65  be in.** use whe
35bd0 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c  n they are deall
35be0 6f 63 61 74 65 64 2e 20 7b 41 31 37 30 32 32 7d  ocated. {A17022}
35bf0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64   Attempting to d
35c00 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74  eallocate a stat
35c10 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75  ic.** mutex resu
35c20 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
35c30 20 62 65 68 61 76 69 6f 72 2e 20 7b 48 31 37 30   behavior. {H170
35c40 32 33 7d 20 53 51 4c 69 74 65 20 6e 65 76 65 72  23} SQLite never
35c50 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20   deallocates.** 
35c60 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20  a static mutex. 
35c70 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
35c80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
35c90 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ter() and sqlite
35ca0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f  3_mutex_try() ro
35cb0 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a  utines attempt.*
35cc0 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74  * to enter a mut
35cd0 65 78 2e 20 7b 48 31 37 30 32 34 7d 20 49 66 20  ex. {H17024} If 
35ce0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 69  another thread i
35cf0 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e  s already within
35d00 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73   the mutex,.** s
35d10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
35d20 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20  er() will block 
35d30 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  and sqlite3_mute
35d40 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74  x_try() will ret
35d50 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55  urn.** SQLITE_BU
35d60 53 59 2e 20 7b 48 31 37 30 32 35 7d 20 20 54 68  SY. {H17025}  Th
35d70 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
35d80 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  try() interface 
35d90 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
35da0 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63  OK].** upon succ
35db0 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 7b  essful entry.  {
35dc0 48 31 37 30 32 36 7d 20 4d 75 74 65 78 65 73 20  H17026} Mutexes 
35dd0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
35de0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
35df0 43 55 52 53 49 56 45 20 63 61 6e 20 62 65 20 65  CURSIVE can be e
35e00 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  ntered multiple 
35e10 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d  times by the sam
35e20 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 7b 48 31  e thread..** {H1
35e30 37 30 32 37 7d 20 49 6e 20 73 75 63 68 20 63 61  7027} In such ca
35e40 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65  ses the,.** mute
35e50 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64  x must be exited
35e60 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72   an equal number
35e70 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65   of times before
35e80 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
35e90 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 7b  ** can enter.  {
35ea0 41 31 37 30 32 38 7d 20 49 66 20 74 68 65 20 73  A17028} If the s
35eb0 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73  ame thread tries
35ec0 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74   to enter any ot
35ed0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d  her.** kind of m
35ee0 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f  utex more than o
35ef0 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f  nce, the behavio
35f00 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
35f10 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53 51 4c 69  ** {H17029} SQLi
35f20 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78  te will never ex
35f30 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65  hibit.** such be
35f40 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77  havior in its ow
35f50 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73  n use of mutexes
35f60 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73  ..**.** Some sys
35f70 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c  tems (for exampl
35f80 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64  e, Windows 95) d
35f90 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68  o not support th
35fa0 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  e operation.** i
35fb0 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71  mplemented by sq
35fc0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
35fd0 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73  ).  On those sys
35fe0 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75  tems, sqlite3_mu
35ff0 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c  tex_try().** wil
36000 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
36010 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 48  SQLITE_BUSY.  {H
36020 31 37 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74  17030} The SQLit
36030 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72  e core only ever
36040 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33   uses.** sqlite3
36050 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 20  _mutex_try() as 
36060 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  an optimization 
36070 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 70  so this is accep
36080 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  table behavior..
36090 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31 7d 20 54  **.** {H17031} T
360a0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
360b0 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65  _leave() routine
360c0 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74   exits a mutex t
360d0 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  hat was.** previ
360e0 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ously entered by
360f0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
36100 2e 20 20 7b 41 31 37 30 33 32 7d 20 54 68 65 20  .  {A17032} The 
36110 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
36120 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20  ndefined if the 
36130 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72  mutex is not cur
36140 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62  rently entered b
36150 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67  y the.** calling
36160 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f   thread or is no
36170 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f  t currently allo
36180 63 61 74 65 64 2e 20 20 7b 48 31 37 30 33 33 7d  cated.  {H17033}
36190 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
361a0 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e  never do either.
361b0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20   {END}.**.** If 
361c0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
361d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
361e0 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d  ter(), sqlite3_m
361f0 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a  utex_try(), or.*
36200 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
36210 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c  leave() is a NUL
36220 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
36230 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e  all three routin
36240 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20  es.** behave as 
36250 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65  no-ops..**.** Se
36260 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
36270 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61  _mutex_held()] a
36280 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  nd [sqlite3_mute
36290 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f  x_notheld()]..*/
362a0 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  .sqlite3_mutex *
362b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
362c0 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73  loc(int);.void s
362d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
362e0 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  e(sqlite3_mutex*
362f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36300 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69  mutex_enter(sqli
36310 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74  te3_mutex*);.int
36320 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
36330 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ry(sqlite3_mutex
36340 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
36350 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c  _mutex_leave(sql
36360 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f  ite3_mutex*);../
36370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
36380 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a  utex Methods Obj
36390 65 63 74 20 7b 48 31 37 31 32 30 7d 20 3c 53 32  ect {H17120} <S2
363a0 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0130>.** EXPERIM
363b0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ENTAL.**.** An i
363c0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
363d0 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e 65  structure define
363e0 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  s the low-level 
363f0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64  routines.** used
36400 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64   to allocate and
36410 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a   use mutexes..**
36420 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65  .** Usually, the
36430 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69   default mutex i
36440 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70  mplementations p
36450 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 74  rovided by SQLit
36460 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69  e are.** suffici
36470 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65  ent, however the
36480 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f 70   user has the op
36490 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75  tion of substitu
364a0 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a  ting a custom.**
364b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
364c0 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20  for specialized 
364d0 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73  deployments or s
364e0 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68  ystems for which
364f0 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20   SQLite.** does 
36500 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 75  not provide a su
36510 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
36520 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63  ation. In this c
36530 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a  ase, the user.**
36540 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70   creates and pop
36550 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e  ulates an instan
36560 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
36570 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20  ture to pass.** 
36580 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
36590 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74  g() along with t
365a0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
365b0 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e  G_MUTEX] option.
365c0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  .** Additionally
365d0 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  , an instance of
365e0 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
365f0 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61  can be used as a
36600 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69  n.** output vari
36610 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69  able when queryi
36620 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f  ng the system fo
36630 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75  r the current mu
36640 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
36650 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65  ation, using the
36660 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
36670 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  GETMUTEX] option
36680 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74  ..**.** The xMut
36690 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65  exInit method de
366a0 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
366b0 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
366c0 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
366d0 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69   system initiali
366e0 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71  zation by the sq
366f0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
36700 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  () function..** 
36710 7b 48 31 37 30 30 31 7d 20 54 68 65 20 78 4d 75  {H17001} The xMu
36720 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20  texInit routine 
36730 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20  shall be called 
36740 62 79 20 53 51 4c 69 74 65 20 6f 6e 63 65 20 66  by SQLite once f
36750 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63  or each.** effec
36760 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71  tive call to [sq
36770 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
36780 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ()]..**.** The x
36790 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20  MutexEnd method 
367a0 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
367b0 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
367c0 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
367d0 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f  of system shutdo
367e0 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  wn by the sqlite
367f0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e  3_shutdown() fun
36800 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d  ction. The.** im
36810 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
36820 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65  this method is e
36830 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61  xpected to relea
36840 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69  se all outstandi
36850 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ng.** resources 
36860 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20  obtained by the 
36870 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d  mutex methods im
36880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73  plementation, es
36890 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73  pecially.** thos
368a0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68  e obtained by th
368b0 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74  e xMutexInit met
368c0 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d 20 54 68  hod. {H17003} Th
368d0 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a 2a  e xMutexEnd().**
368e0 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
368f0 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   be invoked once
36900 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74   for each call t
36910 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  o [sqlite3_shutd
36920 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  own()]..**.** Th
36930 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65  e remaining seve
36940 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65  n methods define
36950 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  d by this struct
36960 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63  ure (xMutexAlloc
36970 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c  ,.** xMutexFree,
36980 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d   xMutexEnter, xM
36990 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c  utexTry, xMutexL
369a0 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64  eave, xMutexHeld
369b0 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f   and.** xMutexNo
369c0 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74  theld) implement
369d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   the following i
369e0 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 70 65  nterfaces (respe
369f0 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20  ctively):.**.** 
36a00 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  <ul>.**   <li>  
36a10 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
36a20 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  lloc()] </li>.**
36a30 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
36a40 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20  3_mutex_free()] 
36a50 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
36a60 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
36a70 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  enter()] </li>.*
36a80 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
36a90 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20  e3_mutex_try()] 
36aa0 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
36ab0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
36ac0 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  leave()] </li>.*
36ad0 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
36ae0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d  e3_mutex_held()]
36af0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
36b00 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
36b10 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69  _notheld()] </li
36b20 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
36b30 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
36b40 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 68 65  ence is that the
36b50 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f   public sqlite3_
36b60 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e  XXX functions en
36b70 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76  umerated.** abov
36b80 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  e silently ignor
36b90 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e  e any invocation
36ba0 73 20 74 68 61 74 20 70 61 73 73 20 61 20 4e 55  s that pass a NU
36bb0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  LL pointer inste
36bc0 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64  ad.** of a valid
36bd0 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54   mutex handle. T
36be0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
36bf0 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64  ns of the method
36c00 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20  s defined.** by 
36c10 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61  this structure a
36c20 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20  re not required 
36c30 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63  to handle this c
36c40 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ase, the results
36c50 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61  .** of passing a
36c60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e   NULL pointer in
36c70 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64  stead of a valid
36c80 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72   mutex handle ar
36c90 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28  e undefined.** (
36ca0 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65 70  i.e. it is accep
36cb0 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65  table to provide
36cc0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
36cd0 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c 74  on that segfault
36ce0 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61  s if.** it is pa
36cf0 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ssed a NULL poin
36d00 74 65 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ter)..**.** The 
36d10 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 65 74  xMutexInit() met
36d20 68 6f 64 20 6d 75 73 74 20 62 65 20 74 68 72 65  hod must be thre
36d30 61 64 73 61 66 65 2e 20 20 49 74 20 6d 75 73 74  adsafe.  It must
36d40 20 62 65 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a   be harmless to.
36d50 2a 2a 20 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78  ** invoke xMutex
36d60 49 6e 69 74 28 29 20 6d 75 74 69 70 6c 65 20 74  Init() mutiple t
36d70 69 6d 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  imes within the 
36d80 73 61 6d 65 20 70 72 6f 63 65 73 73 20 61 6e 64  same process and
36d90 20 77 69 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65   without.** inte
36da0 72 76 65 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  rvening calls to
36db0 20 78 4d 75 74 65 78 45 6e 64 28 29 2e 20 20 53   xMutexEnd().  S
36dc0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
36dd0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
36de0 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75   xMutexInit() mu
36df0 73 74 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  st be no-ops..**
36e00 0a 2a 2a 20 78 4d 75 74 65 78 49 6e 69 74 28 29  .** xMutexInit()
36e10 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51   must not use SQ
36e20 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  Lite memory allo
36e30 63 61 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33  cation ([sqlite3
36e40 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e  _malloc()].** an
36e50 64 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 73  d its associates
36e60 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 78  ).  Similarly, x
36e70 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73  MutexAlloc() mus
36e80 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65  t not use SQLite
36e90 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
36ea0 61 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74  ation for a stat
36eb0 69 63 20 6d 75 74 65 78 2e 20 20 48 6f 77 65 76  ic mutex.  Howev
36ec0 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29  er xMutexAlloc()
36ed0 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a   may use SQLite.
36ee0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
36ef0 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20  tion for a fast 
36f00 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74  or recursive mut
36f10 65 78 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ex..**.** SQLite
36f20 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
36f30 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74   xMutexEnd() met
36f40 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  hod when [sqlite
36f50 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73  3_shutdown()] is
36f60 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20  .** called, but 
36f70 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f  only if the prio
36f80 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78  r call to xMutex
36f90 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53 51  Init returned SQ
36fa0 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78  LITE_OK..** If x
36fb0 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20  MutexInit fails 
36fc0 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69  in any way, it i
36fd0 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c  s expected to cl
36fe0 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74 73  ean up after its
36ff0 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  elf.** prior to 
37000 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79  returning..*/.ty
37010 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
37020 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
37030 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ds sqlite3_mutex
37040 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
37050 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
37060 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28  ethods {.  int (
37070 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69  *xMutexInit)(voi
37080 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  d);.  int (*xMut
37090 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20  exEnd)(void);.  
370a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28  sqlite3_mutex *(
370b0 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e  *xMutexAlloc)(in
370c0 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  t);.  void (*xMu
370d0 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33  texFree)(sqlite3
370e0 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
370f0 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29  d (*xMutexEnter)
37100 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
37110 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
37120 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75  xTry)(sqlite3_mu
37130 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
37140 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71  *xMutexLeave)(sq
37150 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
37160 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65    int (*xMutexHe
37170 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ld)(sqlite3_mute
37180 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
37190 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c  utexNotheld)(sql
371a0 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d  ite3_mutex *);.}
371b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
371c0 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63  F: Mutex Verific
371d0 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b  ation Routines {
371e0 48 31 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e  H17080} <S20130>
371f0 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
37200 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
37210 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c  x_held() and sql
37220 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
37230 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  ld() routines.**
37240 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
37250 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73  r use inside ass
37260 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
37270 2e 20 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53  . {H17081} The S
37280 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65  QLite core.** ne
37290 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72  ver uses these r
372a0 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69  outines except i
372b0 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28  nside an assert(
372c0 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f  ) and applicatio
372d0 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65  ns.** are advise
372e0 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20  d to follow the 
372f0 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65  lead of the core
37300 2e 20 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20  .  {H17082} The 
37310 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f  core only.** pro
37320 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61  vides implementa
37330 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20  tions for these 
37340 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74  routines when it
37350 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
37360 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
37370 44 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31  DEBUG flag.  {A1
37380 37 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d  7087} External m
37390 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
373a0 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79  ions.** are only
373b0 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f   required to pro
373c0 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69  vide these routi
373d0 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45  nes if SQLITE_DE
373e0 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65  BUG is.** define
373f0 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20  d and if NDEBUG 
37400 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a  is not defined..
37410 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54  **.** {H17083} T
37420 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68  hese routines sh
37430 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65  ould return true
37440 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e   if the mutex in
37450 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a   their argument.
37460 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f  ** is held or no
37470 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69  t held, respecti
37480 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c  vely, by the cal
37490 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a  ling thread..**.
374a0 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20  ** {X17084} The 
374b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
374c0 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  s not required t
374d0 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69  o provided versi
374e0 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ons of these.** 
374f0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63  routines that ac
37500 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20  tually work. If 
37510 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
37520 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76  on does not prov
37530 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76  ide working.** v
37540 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65  ersions of these
37550 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68   routines, it sh
37560 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72  ould at least pr
37570 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 61 74  ovide stubs that
37580 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72   always.** retur
37590 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f  n true so that o
375a0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20  ne does not get 
375b0 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 74 69  spurious asserti
375c0 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a  on failures..**.
375d0 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74  ** {H17085} If t
375e0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
375f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
37600 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  d() is a NULL po
37610 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68  inter then.** th
37620 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  e routine should
37630 20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44   return 1.  {END
37640 7d 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75  } This seems cou
37650 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73  nter-intuitive s
37660 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20  ince.** clearly 
37670 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74  the mutex cannot
37680 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64   be held if it d
37690 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20  oes not exist.  
376a0 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72  But the.** the r
376b0 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20  eason the mutex 
376c0 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69  does not exist i
376d0 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75  s because the bu
376e0 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73  ild is not.** us
376f0 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e  ing mutexes.  An
37700 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74  d we do not want
37710 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f   the assert() co
37720 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
37730 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
37740 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20  mutex_held() to 
37750 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a  fail, so a non-z
37760 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a  ero return is.**
37770 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
37780 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b   thing to do.  {
37790 48 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69  H17086} The sqli
377a0 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
377b0 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
377c0 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74   should also ret
377d0 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e  urn 1 when given
377e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
377f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37800 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74  mutex_held(sqlit
37810 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
37820 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
37830 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  theld(sqlite3_mu
37840 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tex*);../*.** CA
37850 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79  PI3REF: Mutex Ty
37860 70 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31  pes {H17001} <H1
37870 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7000>.**.** The 
37880 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
37890 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63  lloc()] interfac
378a0 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  e takes a single
378b0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69   argument.** whi
378c0 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  ch is one of the
378d0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
378e0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ants..**.** The 
378f0 73 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75  set of static mu
37900 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65  texes may change
37910 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65   from one SQLite
37920 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a   release to the.
37930 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
37940 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72  ations that over
37950 72 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ride the built-i
37960 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75  n mutex logic mu
37970 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65  st be.** prepare
37980 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65  d to accommodate
37990 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74   additional stat
379a0 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23  ic mutexes..*/.#
379b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
379c0 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20  TEX_FAST        
379d0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
379e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
379f0 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23  RSIVE        1.#
37a00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
37a10 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
37a20 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  R    2.#define S
37a30 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
37a40 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20  IC_MEM       3  
37a50 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  /* sqlite3_mallo
37a60 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  c() */.#define S
37a70 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
37a80 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20  IC_MEM2      4  
37a90 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23  /* NOT USED */.#
37aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
37ab0 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20  TEX_STATIC_OPEN 
37ac0 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
37ad0 65 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f  e3BtreeOpen() */
37ae0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37af0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
37b00 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  G      5  /* sql
37b10 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f  ite3_random() */
37b20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37b30 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
37b40 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75         6  /* lru
37b50 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64   page list */.#d
37b60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
37b70 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20  EX_STATIC_LRU2  
37b80 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61      7  /* lru pa
37b90 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  ge list */../*.*
37ba0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
37bb0 69 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66  ieve the mutex f
37bc0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
37bd0 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32  nnection {H17002
37be0 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <H17000>.**.**
37bf0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
37c00 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
37c10 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  r the [sqlite3_m
37c20 75 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61  utex] object tha
37c30 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73  t .** serializes
37c40 20 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b   access to the [
37c50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37c60 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68  ion] given in th
37c70 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68  e argument.** wh
37c80 65 6e 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  en the [threadin
37c90 67 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61  g mode] is Seria
37ca0 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  lized..** If the
37cb0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
37cc0 5d 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] is Single-thre
37cd0 61 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65  ad or Multi-thre
37ce0 61 64 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20  ad then this.** 
37cf0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
37d00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
37d10 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  */.sqlite3_mutex
37d20 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74   *sqlite3_db_mut
37d30 65 78 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  ex(sqlite3*);../
37d40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
37d50 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c  ow-Level Control
37d60 20 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c   Of Database Fil
37d70 65 73 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30  es {H11300} <S30
37d80 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  800>.**.** {H113
37d90 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
37da0 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
37db0 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
37dc0 20 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74   a direct call t
37dd0 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f  o the.** xFileCo
37de0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72  ntrol method for
37df0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
37e00 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
37e10 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
37e20 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
37e30 20 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69   database identi
37e40 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
37e50 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31  nd argument. {H1
37e60 31 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d  1302} The.** nam
37e70 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
37e80 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73  e is the name as
37e90 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61  signed to the da
37ea0 74 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a  tabase by the.**
37eb0 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61   <a href="lang_a
37ec0 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41  ttach.html">ATTA
37ed0 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61  CH</a> SQL comma
37ee0 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74  nd that opened t
37ef0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
37f00 7b 48 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74  {H11303} To cont
37f10 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74  rol the main dat
37f20 61 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20  abase file, use 
37f30 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a  the name "main".
37f40 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ** or a NULL poi
37f50 6e 74 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54  nter. {H11304} T
37f60 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
37f70 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
37f80 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  o this routine.*
37f90 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69 72  * are passed dir
37fa0 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f  ectly through to
37fb0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
37fc0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 73  third parameters
37fd0 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65   of.** the xFile
37fe0 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20  Control method. 
37ff0 20 7b 48 31 31 33 30 35 7d 20 54 68 65 20 72 65   {H11305} The re
38000 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
38010 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a  e xFileControl.*
38020 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73  * method becomes
38030 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
38040 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
38050 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36  e..**.** {H11306
38060 7d 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20  } If the second 
38070 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61  parameter (zDbNa
38080 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74  me) does not mat
38090 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ch the name of a
380a0 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62  ny.** open datab
380b0 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53  ase file, then S
380c0 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72  QLITE_ERROR is r
380d0 65 74 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37  eturned. {H11307
380e0 7d 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20  } This error.** 
380f0 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65  code is not reme
38100 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20  mbered and will 
38110 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20  not be recalled 
38120 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  by [sqlite3_errc
38130 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  ode()].** or [sq
38140 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
38150 20 7b 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e   {A11308} The un
38160 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f  derlying xFileCo
38170 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67  ntrol method mig
38180 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72  ht.** also retur
38190 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  n SQLITE_ERROR. 
381a0 20 7b 41 31 31 33 30 39 7d 20 54 68 65 72 65 20   {A11309} There 
381b0 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73  is no way to dis
381c0 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e  tinguish between
381d0 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74  .** an incorrect
381e0 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20   zDbName and an 
381f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74  SQLITE_ERROR ret
38200 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64  urn from the und
38210 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65  erlying.** xFile
38220 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20  Control method. 
38230 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20  {END}.**.** See 
38240 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43  also: [SQLITE_FC
38250 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a  NTL_LOCKSTATE].*
38260 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
38270 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74  le_control(sqlit
38280 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
38290 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70  *zDbName, int op
382a0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
382b0 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69   CAPI3REF: Testi
382c0 6e 67 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31  ng Interface {H1
382d0 31 34 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a  1400} <S30800>.*
382e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
382f0 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20  _test_control() 
38300 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
38310 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e  d to read out in
38320 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20  ternal.** state 
38330 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f  of SQLite and to
38340 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69   inject faults i
38350 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74  nto SQLite for t
38360 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73  esting.** purpos
38370 65 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  es.  The first p
38380 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f  arameter is an o
38390 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68  peration code th
383a0 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
383b0 20 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61   the number, mea
383c0 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74  ning, and operat
383d0 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65  ion of all subse
383e0 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
383f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
38400 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f  erface is not fo
38410 72 20 75 73 65 20 62 79 20 61 70 70 6c 69 63 61  r use by applica
38420 74 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74  tions.  It exist
38430 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20  s solely.** for 
38440 76 65 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f  verifying the co
38450 72 72 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrect operation 
38460 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
38470 62 72 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e  brary.  Dependin
38480 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20  g.** on how the 
38490 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69  SQLite library i
384a0 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73  s compiled, this
384b0 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
384c0 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a   not exist..**.*
384d0 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
384e0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63   the operation c
384f0 6f 64 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e  odes, their mean
38500 69 6e 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65  ings, the parame
38510 74 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b  ters.** they tak
38520 65 2c 20 61 6e 64 20 77 68 61 74 20 74 68 65 79  e, and what they
38530 20 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a   do are all subj
38540 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
38550 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a  thout notice..**
38560 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20   Unlike most of 
38570 74 68 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20  the SQLite API, 
38580 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
38590 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
385a0 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f  to.** operate co
385b0 6e 73 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20  nsistently from 
385c0 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
385d0 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20  he next..*/.int 
385e0 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e  sqlite3_test_con
385f0 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e  trol(int op, ...
38600 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38610 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65  EF: Testing Inte
38620 72 66 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20  rface Operation 
38630 43 6f 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c  Codes {H11410} <
38640 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H11400>.**.** Th
38650 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
38660 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72  e the valid oper
38670 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d  ation code param
38680 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73  eters used.** as
38690 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
386a0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
386b0 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e  test_control()].
386c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72  .**.** These par
386d0 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65 69  ameters and thei
386e0 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73  r meanings are s
386f0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
38700 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  .** without noti
38710 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65  ce.  These value
38720 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e  s are for testin
38730 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e  g purposes only.
38740 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
38750 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
38760 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61 72  any of these par
38770 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a  ameters or the.*
38780 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  * [sqlite3_test_
38790 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
387a0 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
387b0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
387c0 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20  _PRNG_SAVE      
387d0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
387e0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
387f0 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45  TRL_PRNG_RESTORE
38800 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
38810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
38820 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45  STCTRL_PRNG_RESE
38830 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
38840 37 0a 23 64