/ Hex Artifact Content
Login

Artifact fdd4e3109e21431797a22e3696d082c271a454fc:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 20 7b 48 31 30 30 31 30 7d 20 3c 53 36 30  rs {H10010} <S60
0ac0: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  100>.**.** The S
0ad0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e  QLITE_VERSION an
0ae0: 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  d SQLITE_VERSION
0af0: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73  _NUMBER #defines
0b00: 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74   in.** the sqlit
0b10: 65 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66  e3.h file specif
0b20: 79 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66  y the version of
0b30: 20 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69   SQLite with whi
0b40: 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65  ch.** that heade
0b50: 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69  r file is associ
0b60: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
0b70: 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c  "version" of SQL
0b80: 69 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  ite is a string 
0b90: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 58 2e 59  of the form "X.Y
0ba0: 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 70 68 72 61  .Z"..** The phra
0bb0: 73 65 20 22 61 6c 70 68 61 22 20 6f 72 20 22 62  se "alpha" or "b
0bc0: 65 74 61 22 20 6d 69 67 68 74 20 62 65 20 61 70  eta" might be ap
0bd0: 70 65 6e 64 65 64 20 61 66 74 65 72 20 74 68 65  pended after the
0be0: 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c   Z..** The X val
0bf0: 75 65 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73  ue is major vers
0c00: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6c 77 61 79  ion number alway
0c10: 73 20 33 20 69 6e 20 53 51 4c 69 74 65 33 2e 0a  s 3 in SQLite3..
0c20: 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 6f  ** The X value o
0c30: 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e  nly changes when
0c40: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
0c50: 74 69 62 69 6c 69 74 79 20 69 73 0a 2a 2a 20 62  tibility is.** b
0c60: 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69 6e 74  roken and we int
0c70: 65 6e 64 20 74 6f 20 6e 65 76 65 72 20 62 72 65  end to never bre
0c80: 61 6b 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ak backwards com
0c90: 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 54  patibility..** T
0ca0: 68 65 20 59 20 76 61 6c 75 65 20 69 73 20 74 68  he Y value is th
0cb0: 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20  e minor version 
0cc0: 6e 75 6d 62 65 72 20 61 6e 64 20 6f 6e 6c 79 20  number and only 
0cd0: 63 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20  changes when.** 
0ce0: 74 68 65 72 65 20 61 72 65 20 6d 61 6a 6f 72 20  there are major 
0cf0: 66 65 61 74 75 72 65 20 65 6e 68 61 6e 63 65 6d  feature enhancem
0d00: 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 66 6f  ents that are fo
0d10: 72 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  rwards compatibl
0d20: 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 62 61 63  e.** but not bac
0d30: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  kwards compatibl
0d40: 65 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61 6c 75  e..** The Z valu
0d50: 65 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65  e is the release
0d60: 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20 69   number and is i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68 0a  ncremented with.
0d80: 2a 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65 20  ** each release 
0d90: 62 75 74 20 72 65 73 65 74 73 20 62 61 63 6b 20  but resets back 
0da0: 74 6f 20 30 20 77 68 65 6e 65 76 65 72 20 59 20  to 0 whenever Y 
0db0: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 0a  is incremented..
0dc0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
0dd0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0de0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  is an integer th
0df0: 61 74 20 69 73 20 63 6f 6d 70 75 74 65 64 20 61  at is computed a
0e00: 73 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s.** follows:.**
0e10: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
0e20: 3c 70 72 65 3e 0a 2a 2a 20 53 51 4c 49 54 45 5f  <pre>.** SQLITE_
0e30: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 3d  VERSION_NUMBER =
0e40: 20 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31   X*1000000 + Y*1
0e50: 30 30 30 20 2b 20 5a 0a 2a 2a 20 3c 2f 70 72 65  000 + Z.** </pre
0e60: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
0e70: 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69  *.** Since versi
0e80: 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74  on 3.6.18, SQLit
0e90: 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61  e source code ha
0ea0: 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e  s been stored in
0eb0: 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
0ec0: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73  "http://www.foss
0ed0: 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 66 6f 73  il-scm.org/">fos
0ee0: 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  sil configuratio
0ef0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20  n management.** 
0f00: 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 54 68 65  system</a>.  The
0f10: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0f20: 44 0a 2a 2a 20 6d 61 63 72 6f 20 69 73 20 61 20  D.** macro is a 
0f30: 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 65  string which ide
0f40: 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69 63  ntifies a partic
0f50: 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66  ular check-in of
0f60: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69   SQLite.** withi
0f70: 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74  n its configurat
0f80: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73  ion management s
0f90: 79 73 74 65 6d 2e 20 20 54 68 65 20 73 74 72 69  ystem.  The stri
0fa0: 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  ng contains the.
0fb0: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
0fc0: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e   of the check-in
0fd0: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48   (UTC) and an SH
0fe0: 41 31 20 68 61 73 68 20 6f 66 20 74 68 65 20 65  A1 hash of the e
0ff0: 6e 74 69 72 65 0a 2a 2a 20 73 6f 75 72 63 65 20  ntire.** source 
1000: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tree..**.** See 
1010: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c  also: [sqlite3_l
1020: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a  ibversion()],.**
1030: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
1040: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20  sion_number()], 
1050: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75  and [sqlite3_sou
1060: 72 63 65 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  rceid()]..**.** 
1070: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48  Requirements: [H
1080: 31 30 30 31 31 5d 20 5b 48 31 30 30 31 34 5d 0a  10011] [H10014].
1090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10a0: 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20  E_VERSION       
10b0: 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66   "--VERS--".#def
10c0: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
10d0: 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53  ON_NUMBER --VERS
10e0: 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65  ION-NUMBER--.#de
10f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1100: 43 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f  CE_ID      "--SO
1110: 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a  URCE-ID--"../*.*
1120: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
1130: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
1140: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31  sion Numbers {H1
1150: 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a  0020} <S60100>.*
1160: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
1170: 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a  te3_version.**.*
1180: 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63  * These interfac
1190: 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73  es provide the s
11a0: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
11b0: 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56  as the [SQLITE_V
11c0: 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c  ERSION],.** [SQL
11d0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
11e0: 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  ER], and [SQLITE
11f0: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23 64 65 66  _SOURCE_ID] #def
1200: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64  ines in the head
1210: 65 72 2c 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  er,.** but are a
1220: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1230: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1240: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
1250: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73   file.  Cautious
1260: 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  .** programmers 
1270: 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 6e  might include an
1280: 20 61 73 73 65 72 74 20 69 6e 20 74 68 65 69 72   assert in their
1290: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
12a0: 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73  verify that.** s
12b0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
12c0: 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79  n_number() alway
12d0: 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  s returns the va
12e0: 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56  lue.** [SQLITE_V
12f0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 61  ERSION_NUMBER] a
1300: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1310: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1320: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1330: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1340: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1350: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
1360: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1370: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1380: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1390: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
13a0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
13b0: 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   );.** </pre></b
13c0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
13d0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
13e0: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
13f0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  on returns the s
1400: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
1410: 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20  as is.** in the 
1420: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1430: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1440: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
1450: 20 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20   is provided.** 
1460: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1470: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
1480: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1490: 61 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73  ave direct acces
14a0: 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63  s to string.** c
14b0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14c0: 74 68 65 20 44 4c 4c 2e 20 20 53 69 6d 69 6c 61  the DLL.  Simila
14d0: 72 6c 79 2c 20 74 68 65 20 73 71 6c 69 74 65 33  rly, the sqlite3
14e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
14f0: 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tion.** returns 
1500: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
1510: 74 69 6f 6e 20 61 73 20 69 73 20 69 6e 20 74 68  tion as is in th
1520: 65 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  e [SQLITE_SOURCE
1530: 5f 49 44 5d 20 23 64 65 66 69 6e 65 20 6f 66 0a  _ID] #define of.
1540: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 20 66 69  ** the header fi
1550: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  le..**.** Requir
1560: 65 6d 65 6e 74 73 3a 20 5b 48 31 30 30 32 31 5d  ements: [H10021]
1570: 20 5b 48 31 30 30 32 32 5d 20 5b 48 31 30 30 32   [H10022] [H1002
1580: 33 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  3].*/.SQLITE_EXT
1590: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
15a0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
15b0: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
15c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
15d0: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
15e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
15f0: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
1600: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1610: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1620: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1630: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1640: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1650: 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31  Threadsafe {H101
1660: 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a  00} <S60100>.**.
1670: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1680: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1690: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
16a0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
16b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
16c0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
16d0: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
16e0: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
16f0: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1700: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1710: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1720: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1730: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1740: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1750: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1760: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1770: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1780: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1790: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
17a0: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
17b0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
17c0: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
17d0: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
17e0: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
17f0: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1800: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1810: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1820: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1830: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1840: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1850: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1860: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1870: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1880: 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  d..** The defaul
1890: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
18a0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
18b0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
18c0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
18d0: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
18e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
18f0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1900: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1910: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1920: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1930: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1940: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1950: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1960: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1970: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1980: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1990: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
19a0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
19b0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
19c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
19d0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
19e0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
19f0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1a00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
1a10: 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74  DSAFE=1 then mut
1a20: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1a30: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1a40: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1a50: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1a60: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1a70: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1a80: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
1a90: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
1aa0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
1ab0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
1ac0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1ad0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
1ae0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1af0: 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  ].  The return v
1b00: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e  alue of this fun
1b10: 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f  ction shows.** o
1b20: 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20  nly the default 
1b30: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
1b40: 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75  ting, not any ru
1b50: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a  n-time changes.*
1b60: 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  * to that settin
1b70: 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  g..**.** See the
1b80: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1b90: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
1ba0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
1bb0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1bc0: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
1bd0: 5b 48 31 30 31 30 31 5d 20 5b 48 31 30 31 30 32  [H10101] [H10102
1be0: 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1bf0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1c00: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c10: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1c20: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1c30: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1c40: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1c50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c60: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1c70: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1c80: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
1c90: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
1ca0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
1cb0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
1cc0: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
1cd0: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
1ce0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1cf0: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1d00: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1d10: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1d20: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1d30: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1d40: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1d50: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1d70: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1d80: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
1d90: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
1da0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
1db0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
1dc0: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
1dd0: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
1de0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1df0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e00: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1e10: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1e20: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1e30: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1e40: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1e50: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1e60: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1e70: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1e80: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1e90: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ea0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1eb0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1ec0: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1ed0: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1ee0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1ef0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1f00: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1f10: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1f20: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1f30: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1f40: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1f50: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1f60: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1f70: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1f80: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1f90: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1fa0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1fb0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1fc0: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1fd0: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1fe0: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1ff0: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
2000: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
2010: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
2020: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
2030: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
2040: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  nly..**.** Requi
2050: 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 32 30 31  rements: [H10201
2060: 5d 20 5b 48 31 30 32 30 32 5d 0a 2a 2f 0a 23 69  ] [H10202].*/.#i
2070: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
2080: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
2090: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
20a0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
20b0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
20c0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
20d0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
20e0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
20f0: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
2100: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
2110: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
2120: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
2130: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
2140: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
2150: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2160: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
2170: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
2180: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
2190: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
21a0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
21b0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
21c0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
21d0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
21e0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
21f0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
2200: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
2210: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
2220: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
2230: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
2240: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
2250: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
2260: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
2270: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
2280: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
2290: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
22a0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
22b0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
22c0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
22d0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
22e0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
22f0: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
2300: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
2310: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2320: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2330: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2340: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2350: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
2360: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
2370: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2380: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
2390: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
23a0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
23b0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
23c0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
23d0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
23e0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
23f0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2400: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
2410: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
2420: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2430: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2440: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2450: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2460: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2470: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2480: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
2490: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
24a0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
24b0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
24c0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
24d0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
24e0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
24f0: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
2500: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
2510: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
2520: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2530: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2540: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2550: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2560: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2570: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2580: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
2590: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
25a0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
25b0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
25c0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
25d0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
25e0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
25f0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2600: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2610: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2620: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2630: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2640: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2650: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2660: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2670: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2680: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2690: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
26a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26b0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
26c0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
26d0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
26e0: 73 3a 0a 2a 2a 20 5b 48 31 32 30 31 31 5d 20 5b  s:.** [H12011] [
26f0: 48 31 32 30 31 32 5d 20 5b 48 31 32 30 31 33 5d  H12012] [H12013]
2700: 20 5b 48 31 32 30 31 34 5d 20 5b 48 31 32 30 31   [H12014] [H1201
2710: 35 5d 20 5b 48 31 32 30 31 39 5d 0a 2a 2f 0a 69  5] [H12019].*/.i
2720: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2730: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2740: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2750: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2760: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2770: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2780: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
2790: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
27a0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
27b0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
27c0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
27d0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
27e0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
27f0: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2800: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2810: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2820: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2830: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2840: 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30 30   {H12100} <S1000
2850: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2860: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2870: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
2880: 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e  nient way of run
2890: 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ning one or more
28a0: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
28b0: 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ts without havin
28c0: 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74  g to write a lot
28d0: 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65   of C code.  The
28e0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a   UTF-8 encoded.*
28f0: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2900: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2910: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2920: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2930: 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65  3_exec()..** The
2940: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2950: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2960: 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65   one until eithe
2970: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a  r an error or.**
2980: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
2990: 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72   encountered, or
29a0: 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20   until they are 
29b0: 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33  all done.  The 3
29c0: 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
29d0: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63  is an optional c
29e0: 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20  allback that is 
29f0: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2a00: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79   each row of any
2a10: 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74   query.** result
2a20: 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68  s produced by th
2a30: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2a40: 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
2a50: 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65  eter tells where
2a60: 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79  .** to write any
2a70: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e   error messages.
2a80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72  .**.** The error
2a90: 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20   message passed 
2aa0: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
2ab0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69   5th parameter i
2ac0: 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d  s held.** in mem
2ad0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2ae0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2af0: 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20  c()].  To avoid 
2b00: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a  a memory leak,.*
2b10: 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70  * the calling ap
2b20: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
2b30: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
2b40: 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72  ree()] on any er
2b50: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72  ror.** message r
2b60: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
2b70: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2b80: 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
2b90: 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
2ba0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2bb0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
2bc0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
2bd0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2be0: 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  er is NULL or an
2bf0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a   empty string.**
2c00: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   or a string con
2c10: 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69  taining only whi
2c20: 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d  tespace and comm
2c30: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
2c40: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2c50: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2c60: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2c70: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
2c80: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2c90: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
2ca0: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
2cb0: 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20   in terms of.** 
2cc0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2cd0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2ce0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2cf0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d00: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  )]..** The sqlit
2d10: 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e  e3_exec() routin
2d20: 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74  e does nothing t
2d30: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
2d40: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f  hat cannot be do
2d50: 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ne.** by [sqlite
2d60: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2d70: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d80: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2d90: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
2da0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
2db0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2dc0: 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20  e3_exec()] must 
2dd0: 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20  be an valid and 
2de0: 6f 70 65 6e 0a 2a 2a 20 5b 64 61 74 61 62 61 73  open.** [databas
2df0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
2e00: 2a 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73  *.** The databas
2e10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2e20: 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20  t not be closed 
2e30: 77 68 69 6c 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  while.** [sqlite
2e40: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
2e50: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
2e60: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2e70: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
2e80: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
2e90: 66 72 65 65 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  free.** the memo
2ea0: 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20  ry that *errmsg 
2eb0: 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ec0: 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72   at once the err
2ed0: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 69 73  or.** message is
2ee0: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
2ef0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  d..**.** The SQL
2f00: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2f10: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2f20: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2f30: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  _exec()].** must
2f40: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2f50: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
2f60: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
2f70: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
2f80: 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
2f90: 31 30 31 5d 20 5b 48 31 32 31 30 32 5d 20 5b 48  101] [H12102] [H
2fa0: 31 32 31 30 34 5d 20 5b 48 31 32 31 30 35 5d 20  12104] [H12105] 
2fb0: 5b 48 31 32 31 30 37 5d 20 5b 48 31 32 31 31 30  [H12107] [H12110
2fc0: 5d 20 5b 48 31 32 31 31 33 5d 20 5b 48 31 32 31  ] [H12113] [H121
2fd0: 31 36 5d 0a 2a 2a 20 5b 48 31 32 31 31 39 5d 20  16].** [H12119] 
2fe0: 5b 48 31 32 31 32 32 5d 20 5b 48 31 32 31 32 35  [H12122] [H12125
2ff0: 5d 20 5b 48 31 32 31 33 31 5d 20 5b 48 31 32 31  ] [H12131] [H121
3000: 33 34 5d 20 5b 48 31 32 31 33 37 5d 20 5b 48 31  34] [H12137] [H1
3010: 32 31 33 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2138].*/.int sql
3020: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
3030: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
3040: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3050: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
3060: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
3070: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
3080: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3090: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
30a0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
30b0: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
30c0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
30d0: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
30e0: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
30f0: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
3100: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
3110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3120: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
3130: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
3140: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
3150: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
3160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3170: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
3180: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
3190: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
31a0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
31b0: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
31c0: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
31d0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
31e0: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
31f0: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
3200: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
3210: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
3220: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
3230: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
3240: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
3250: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
3260: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
3270: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
3280: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
3290: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
32a0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
32b0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
32c0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
32d0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
32e0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
32f0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
3300: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
3310: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
3320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
3330: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
3340: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
3350: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
3360: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
3370: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
3380: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
3390: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
33a0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
33b0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
33c0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
33d0: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
33e0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
33f0: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
3400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
3410: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
3420: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
3430: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
3440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
3450: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
3460: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
3470: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
3480: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
3490: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
34a0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
34b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
34c0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
34d0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
34e0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
34f0: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
3500: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
3510: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3520: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
3530: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
3540: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
3550: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
3560: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
3570: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
3580: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
3590: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
35a0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
35b0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
35c0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
35d0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
35e0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
35f0: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
3600: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
3610: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
3620: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
3630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3640: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
3650: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3660: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
3670: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
3680: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
3690: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
36a0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
36b0: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
36c0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
36d0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
36e0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
36f0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
3700: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
3710: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
3720: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
3730: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
3740: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
3750: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
3760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
3770: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
3780: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
3790: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
37a0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
37b0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
37c0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
37d0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
37e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
37f0: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
3800: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3810: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
3820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3830: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
3840: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
3850: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
3860: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
3870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
3880: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
3890: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
38a0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
38b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
38c0: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
38d0: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
38e0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
38f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
3900: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
3910: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
3920: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
3930: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
3940: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
3950: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
3960: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
3970: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
3980: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
3990: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
39a0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
39b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
39c0: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
39d0: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
39e0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
39f0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
3a00: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
3a10: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
3a20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3a30: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
3a40: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
3a50: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
3a60: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
3a70: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
3a80: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
3a90: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
3aa0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
3ab0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
3ac0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
3ad0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
3ae0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3af0: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
3b00: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
3b10: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
3b20: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
3b30: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
3b40: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
3b50: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
3b60: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
3b70: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
3b80: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
3b90: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
3ba0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
3bb0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
3bc0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
3bd0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
3be0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
3bf0: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
3c00: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
3c10: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
3c20: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
3c30: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
3c40: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
3c50: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
3c60: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
3c70: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
3c80: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
3c90: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
3ca0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
3cb0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
3cc0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
3cd0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
3ce0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
3cf0: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
3d00: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
3d10: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
3d20: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
3d30: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
3d40: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3d50: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
3d60: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
3d70: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
3d80: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
3d90: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
3da0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
3db0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
3dc0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
3dd0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
3de0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
3df0: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
3e00: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
3e10: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
3e20: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
3e30: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
3e40: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
3e50: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
3e60: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
3e70: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
3e80: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3e90: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
3ea0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
3eb0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
3ec0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
3ed0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
3ee0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
3ef0: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
3f00: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
3f10: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3f20: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
3f30: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
3f40: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
3f50: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
3f60: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
3f70: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
3f80: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
3f90: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
3fa0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
3fb0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
3fc0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
3fd0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
3ff0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4010: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4020: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4030: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4040: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4050: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4060: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4070: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4080: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4090: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
40a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
40b0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
40c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
40d0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
40e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
40f0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4110: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4120: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4130: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4140: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4150: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4160: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4170: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4190: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
41a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
41b0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
41c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
41d0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
41e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
41f0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4210: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4220: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4230: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4240: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4250: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4260: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4270: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4280: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4290: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
42a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
42b0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
42c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
42d0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
42e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
42f0: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4310: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4320: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4330: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4350: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4360: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4370: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4390: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
43a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
43b0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
43c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
43d0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
43e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
43f0: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4410: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
4420: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
4430: 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a 2f  ED | (1<<8) )../
4440: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
4450: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
4460: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
4470: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
4480: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
4490: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
44a0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
44b0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
44c0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
44d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
44e0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
44f0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
4500: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
4510: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
4520: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
4530: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
4540: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4550: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
4560: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
4570: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
4580: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4590: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
45a0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
45b0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
45c0: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
45d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
45e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
45f0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
4600: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4610: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
4620: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4630: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4640: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
4650: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
4660: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
4670: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4680: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
4690: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
46a0: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
46b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
46c0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
46d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
46e0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
46f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4700: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
4710: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4720: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
4730: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4740: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
4750: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
4760: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
4770: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4780: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
4790: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
47a0: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
47b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
47c0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
47d0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
47e0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
47f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4800: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
4810: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
4820: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
4830: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4840: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
4850: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
4860: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
4870: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4880: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
4890: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
48a0: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
48b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
48c0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
48d0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
48e0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
48f0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
4900: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4910: 29 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ) */../*.** CAPI
4920: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
4930: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
4940: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
4950: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
4960: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
4970: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
4980: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4990: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
49a0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
49b0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
49c0: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
49d0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
49e0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
49f0: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
4a00: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
4a10: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
4a20: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
4a30: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
4a40: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
4a50: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
4a60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
4a70: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
4a80: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
4a90: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
4aa0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
4ab0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4ac0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
4ad0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
4ae0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
4af0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
4b00: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
4b10: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
4b20: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
4b30: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
4b40: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
4b50: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
4b60: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
4b70: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
4b80: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
4b90: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
4ba0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
4bb0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
4bc0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
4bd0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
4be0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
4bf0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
4c00: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
4c10: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
4c20: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
4c30: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
4c40: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
4c50: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
4c60: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
4c70: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
4c80: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
4c90: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
4ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4cb0: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
4cc0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
4cd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4ce0: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
4cf0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
4d00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4d10: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
4d20: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
4d30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4d40: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
4d50: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
4d60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4d70: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
4d80: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
4d90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4da0: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
4db0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
4dc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4dd0: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
4de0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
4df0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4e00: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
4e10: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
4e20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4e30: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
4e40: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
4e50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
4e60: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
4e70: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
4e80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
4e90: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
4ea0: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
4eb0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
4ec0: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
4ed0: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
4ee0: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
4ef0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
4f00: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
4f10: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
4f20: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
4f30: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
4f40: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
4f50: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
4f60: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
4f70: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
4f80: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
4f90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4fa0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
4fb0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
4fc0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
4fd0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
4fe0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
4ff0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
5000: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
5010: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
5020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5030: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
5040: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
5050: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
5060: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
5070: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
5080: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
5090: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
50a0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
50b0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
50c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
50d0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
50e0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
50f0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5100: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5110: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5120: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5130: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5140: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5150: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5160: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5170: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5180: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5190: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
51a0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
51b0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
51c0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
51d0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
51e0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
51f0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
5200: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
5210: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
5220: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
5230: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
5240: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
5250: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
5260: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
5270: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
5280: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
5290: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
52a0: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
52b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
52c0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
52d0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
52e0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
52f0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
5300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
5310: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
5320: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
5330: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
5340: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
5350: 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c  andle {H11110} <
5360: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20110>.**.** An
5370: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
5380: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
5390: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
53a0: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  n the .** [sqlit
53b0: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65  e3_vfs | OS inte
53c0: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49  rface layer].  I
53d0: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
53e0: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d  erface.** implem
53f0: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
5400: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
5410: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
5420: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
5430: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
5440: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
5450: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
5460: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
5470: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
5480: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5490: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
54a0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
54b0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
54c0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
54d0: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
54e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
54f0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
5500: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
5510: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
5520: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
5530: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
5540: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
5550: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
5560: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
5570: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
5580: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
5590: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
55a0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b  Methods Object {
55b0: 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31 30 3e  H11120} <S20110>
55c0: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
55d0: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
55e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f  [sqlite3_vfs] xO
55f0: 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  pen method popul
5600: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
5610: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
5620: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
5630: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
5640: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
5650: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
5660: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
5670: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
5680: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
5690: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
56a0: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
56b0: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
56c0: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
56d0: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
56e0: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
56f0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
5700: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
5710: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
5720: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
5730: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
5740: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
5750: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
5760: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
5770: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
5780: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
5790: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
57a0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
57b0: 65 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65  even if the xOpe
57c0: 6e 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  n reported that 
57d0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
57e0: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
57f0: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
5800: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
5810: 67 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e  g a failed xOpen
5820: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78  .** is for the x
5830: 4f 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20  Open to set the 
5840: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
5850: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f  thods element to
5860: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
5870: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
5880: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
5890: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
58a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
58b0: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
58c0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
58d0: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
58e0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
58f0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
5900: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
5910: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
5920: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
5930: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
5940: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
5950: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
5960: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
5970: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
5980: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
5990: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
59a0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
59b0: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
59c0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
59d0: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
59e0: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
59f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
5a00: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
5a10: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
5a20: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
5a30: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
5a40: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
5a50: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
5a60: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
5a70: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
5a80: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
5a90: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
5aa0: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
5ab0: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
5ac0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
5ad0: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
5ae0: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
5af0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
5b00: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
5b10: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
5b20: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
5b30: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
5b40: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
5b50: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
5b60: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
5b70: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
5b80: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
5b90: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
5ba0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
5bb0: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
5bc0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
5bd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
5be0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
5bf0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
5c00: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
5c10: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
5c20: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
5c30: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
5c40: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
5c50: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
5c60: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
5c70: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
5c80: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
5c90: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
5ca0: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
5cb0: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
5cc0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
5cd0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
5ce0: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
5cf0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
5d00: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
5d10: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
5d20: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
5d30: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
5d40: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
5d50: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
5d60: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
5d70: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
5d80: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
5d90: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
5da0: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
5db0: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
5dc0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
5dd0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
5de0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
5df0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
5e00: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
5e10: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
5e20: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
5e30: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
5e40: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
5e50: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
5e60: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
5e70: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
5e80: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
5e90: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
5ea0: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
5eb0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
5ec0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
5ed0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
5ee0: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
5ef0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
5f00: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
5f10: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
5f20: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
5f30: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a  oid conflicts..*
5f40: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
5f50: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
5f60: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
5f70: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
5f80: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
5f90: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
5fa0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
5fb0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
5fc0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
5fd0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
5fe0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
5ff0: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
6000: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
6010: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6020: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
6030: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
6040: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
6050: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
6060: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
6070: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
6080: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6090: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
60a0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
60b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
60c0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
60d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
60e0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
60f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6100: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
6110: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6120: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
6130: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6140: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
6150: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6160: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
6170: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6180: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
6190: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
61a0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
61b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
61c0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
61d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
61e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
61f0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
6200: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6210: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6220: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6230: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6240: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6250: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6260: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
6270: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6280: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6290: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
62a0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
62b0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
62c0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
62d0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
62e0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
62f0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6300: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6310: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6320: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6330: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6340: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6350: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6360: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
6370: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6380: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6390: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
63a0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
63b0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
63c0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
63d0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
63e0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
63f0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6400: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6410: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6420: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6430: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
6440: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
6450: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
6460: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
6470: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
6480: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
6490: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
64a0: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
64b0: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
64c0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
64d0: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
64e0: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
64f0: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
6500: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
6510: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
6520: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
6530: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
6540: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
6550: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
6560: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6570: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6580: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
6590: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
65a0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
65b0: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
65c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
65d0: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
65e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
65f0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
6600: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
6610: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
6620: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
6630: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
6640: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
6650: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
6660: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
6670: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
6680: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
6690: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
66a0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
66b0: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
66c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
66d0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
66e0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
66f0: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
6700: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
6710: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
6720: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
6730: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6740: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
6750: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
6760: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6770: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
6780: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
6790: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
67a0: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
67b0: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
67c0: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
67d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
67e0: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
67f0: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
6800: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
6810: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
6820: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
6830: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
6840: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
6850: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
6860: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
6870: 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 48 31 31  rol Opcodes {H11
6880: 33 31 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a  310} <S30800>.**
6890: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
68a0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
68b0: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
68c0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
68d0: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
68e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
68f0: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
6900: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
6910: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
6920: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
6930: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
6940: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
6950: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
6960: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
6970: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
6980: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
6990: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
69a0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
69b0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
69c0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
69d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
69e0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
69f0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
6a00: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6a10: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
6a20: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
6a30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6a40: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
6a50: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
6a60: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
6a70: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
6a80: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
6a90: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
6aa0: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
6ab0: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
6ac0: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
6ad0: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
6ae0: 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ned..*/.#define 
6af0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6b00: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31 0a  KSTATE        1.
6b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
6b20: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
6b30: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6b40: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
6b50: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33 0a  ROXYFILE      3.
6b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6b70: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
6b80: 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43        4../*.** C
6b90: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
6ba0: 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c  andle {H17110} <
6bb0: 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20130>.**.** Th
6bc0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
6bd0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
6be0: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
6bf0: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
6c00: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
6c10: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
6c20: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
6c30: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
6c40: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
6c50: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
6c60: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
6c70: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
6c80: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
6c90: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
6ca0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
6cb0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
6cc0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
6cd0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
6ce0: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
6cf0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
6d00: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
6d10: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
6d20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6d30: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
6d40: 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53  ject {H11140} <S
6d50: 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20  20100>.**.** An 
6d60: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
6d70: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
6d80: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
6d90: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
6da0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
6db0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
6dc0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
6dd0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
6de0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
6df0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
6e00: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
6e10: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
6e20: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
6e30: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
6e40: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
6e50: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
6e60: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
6e70: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
6e80: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
6e90: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
6ea0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
6eb0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
6ec0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
6ed0: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
6ee0: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
6ef0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
6f00: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
6f10: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
6f20: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
6f30: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
6f40: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
6f50: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
6f60: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
6f70: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
6f80: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
6f90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
6fa0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
6fb0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
6fc0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
6fd0: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
6fe0: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
6ff0: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
7000: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
7010: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
7020: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
7030: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
7040: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
7050: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
7060: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
7070: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
7080: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
7090: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
70a0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
70b0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
70c0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
70d0: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
70e0: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
70f0: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
7100: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
7110: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
7120: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
7130: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
7140: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
7150: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
7160: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
7170: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7180: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
7190: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
71a0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
71b0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
71c0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
71d0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
71e0: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
71f0: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
7200: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
7210: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
7220: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
7230: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
7240: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
7250: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
7260: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
7270: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
7280: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
7290: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
72a0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
72b0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
72c0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
72d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
72e0: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
72f0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
7300: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
7310: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
7320: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
7330: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
7340: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
7350: 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  l guarantee that
7360: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
7370: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
7380: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
7390: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
73a0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
73b0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
73c0: 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74  thname().  SQLit
73d0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
73e0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
73f0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
7400: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
7410: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
7420: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
7430: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
7440: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
7450: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
7460: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
7470: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
7480: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
7490: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
74a0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
74b0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
74c0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
74d0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
74e0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f   parameter is xO
74f0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
7500: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
7510: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
7520: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
7530: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
7540: 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74  ile.  Whenever t
7550: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
7560: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
7570: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
7580: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
7590: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
75a0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
75b0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
75c0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
75d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
75e0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
75f0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
7600: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
7610: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
7620: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
7630: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
7640: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
7650: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
7660: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
7670: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
7680: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
7690: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
76a0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
76b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
76c0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
76d0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
76e0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
76f0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
7700: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
7710: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
7720: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
7730: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
7740: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
7750: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
7760: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
7770: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
7780: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
7790: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
77a0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
77b0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
77c0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
77d0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
77e0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
77f0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7800: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
7810: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7820: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
7830: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7840: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
7850: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
7860: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
7870: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
7880: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7890: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
78a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
78b0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
78c0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
78d0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
78e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
78f0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
7900: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
7910: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
7920: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
7930: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
7940: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
7950: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
7960: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
7970: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
7980: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
7990: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
79a0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
79b0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
79c0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
79d0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
79e0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
79f0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
7a00: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
7a10: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
7a20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
7a30: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
7a40: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
7a50: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
7a60: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
7a70: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
7a80: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
7a90: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
7aa0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
7ab0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
7ac0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
7ad0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
7ae0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
7af0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
7b00: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
7b10: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
7b20: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
7b30: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7b40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
7b50: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
7b60: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
7b70: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
7b80: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
7b90: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
7ba0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
7bb0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
7bc0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
7bd0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
7be0: 73 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  sed.  The [SQLIT
7bf0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
7c00: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
7c10: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64   set for TEMP  d
7c20: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61  atabases, journa
7c30: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f  ls and for subjo
7c40: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  urnals..**.** Th
7c50: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
7c60: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
7c70: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
7c80: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
7c90: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
7ca0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
7cb0: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
7cc0: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
7cd0: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
7ce0: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
7cf0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
7d00: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
7d10: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
7d20: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
7d30: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
7d40: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
7d50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7d60: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
7d70: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
7d80: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
7d90: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
7da0: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
7db0: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
7dc0: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
7dd0: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
7de0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
7df0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7e00: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
7e10: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
7e20: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65  ess..**.** At le
7e30: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
7e40: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
7e50: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
7e60: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
7e70: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
7e80: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
7e90: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
7ea0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
7eb0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
7ec0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
7ed0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
7ee0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
7ef0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
7f00: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
7f10: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
7f20: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
7f30: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
7f40: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7f50: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
7f60: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
7f70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7f80: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
7f90: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
7fa0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
7fb0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
7fc0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
7fd0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
7fe0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
7ff0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
8000: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
8010: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
8020: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
8030: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
8040: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
8050: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  call..**.** The 
8060: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8070: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
8080: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
8090: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
80a0: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
80b0: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
80c0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
80d0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
80e0: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
80f0: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
8100: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
8110: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
8120: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
8130: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
8140: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
8150: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
8160: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
8170: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
8180: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  ** SQLite will a
8190: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
81a0: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
81b0: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
81c0: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
81d0: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
81e0: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
81f0: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
8200: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
8210: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
8220: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
8230: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
8240: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
8250: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
8260: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
8270: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
8280: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
8290: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
82a0: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
82b0: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
82c0: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
82d0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
82e0: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
82f0: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
8300: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
8310: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
8320: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
8330: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
8340: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
8350: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
8360: 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  me() interfaces.
8370: 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  ** are not stric
8380: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
8390: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
83a0: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
83b0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
83c0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
83d0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
83e0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
83f0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
8400: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
8410: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
8420: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
8430: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
8440: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
8450: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
8460: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
8470: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
8480: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
8490: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
84a0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
84b0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
84c0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
84d0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
84e0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
84f0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65  onds given.  The
8500: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
8510: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
8520: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
8530: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
8540: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
8550: 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64  ime..**.*/.typed
8560: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
8570: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
8580: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
8590: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
85a0: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
85b0: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
85c0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a  version number *
85d0: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
85e0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
85f0: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
8600: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
8610: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
8620: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
8630: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
8640: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
8650: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
8660: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
8670: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
8680: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
8690: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
86a0: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
86b0: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
86c0: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
86d0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
86e0: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
86f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
8700: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
8710: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
8720: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8730: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
8740: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
8750: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
8760: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
8770: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
8780: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
8790: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
87a0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
87b0: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
87c0: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
87d0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
87e0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
87f0: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
8800: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
8810: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
8820: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
8830: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
8840: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
8850: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
8860: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
8870: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
8880: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
8890: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
88a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
88b0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
88c0: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
88d0: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
88e0: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
88f0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
8900: 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
8910: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
8920: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
8930: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
8940: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
8950: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
8960: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
8970: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
8980: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8990: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
89a0: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
89b0: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
89c0: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
89d0: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
89e0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
89f0: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
8a00: 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64  ;.  /* New field
8a10: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
8a20: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
8a30: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
8a40: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
8a50: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
8a60: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
8a70: 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ens. */.};../*.*
8a80: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
8a90: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
8aa0: 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31  s VFS method {H1
8ab0: 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a  1190} <H11140>.*
8ac0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8ad0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
8ae0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
8af0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
8b00: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
8b10: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
8b20: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
8b30: 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79  ect. {END}  They
8b40: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
8b50: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
8b60: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
8b70: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
8b80: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
8b90: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
8ba0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
8bb0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
8bc0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
8bd0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
8be0: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
8bf0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
8c00: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
8c10: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
8c20: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
8c30: 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64  ile is both read
8c40: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
8c50: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
8c60: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
8c70: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
8c80: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
8c90: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
8ca0: 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65  readable..*/.#de
8cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
8cc0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
8cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
8ce0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
8cf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8d00: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
8d10: 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   2../*.** CAPI3R
8d20: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
8d30: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
8d40: 79 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30  y {H10130} <S200
8d50: 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a  00><S30100>.**.*
8d60: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
8d70: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
8d80: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
8d90: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
8da0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
8db0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
8dc0: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
8dd0: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
8de0: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
8df0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
8e00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
8e10: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
8e20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8e30: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
8e40: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
8e50: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
8e60: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
8e70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
8e80: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
8e90: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
8ea0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
8eb0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
8ec0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
8ed0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
8ee0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
8ef0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
8f00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
8f10: 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66  ().  Only an eff
8f20: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
8f30: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
8f40: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
8f50: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
8f60: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
8f70: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
8f80: 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41   no-ops..**.** A
8f90: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
8fa0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
8fb0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
8fc0: 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
8fd0: 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
8fe0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
8ff0: 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
9000: 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
9010: 61 6c 69 7a 65 28 29 2e 20 20 4f 6e 6c 79 0a 2a  alize().  Only.*
9020: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
9030: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
9040: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
9050: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
9060: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
9070: 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  r calls to sqlit
9080: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
9090: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
90a0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  s..**.** Among o
90b0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c  ther things, sql
90c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
90d0: 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  ) shall invoke.*
90e0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
90f0: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
9100: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9110: 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76  n().** shall inv
9120: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
9130: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nd()..**.** The 
9140: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9150: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
9160: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
9170: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
9180: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
9190: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
91a0: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
91b0: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
91c0: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
91d0: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
91e0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
91f0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
9200: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
9210: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
9220: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
9230: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
9240: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
9250: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9260: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
9270: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
9280: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
9290: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
92a0: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
92b0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
92c0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
92d0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
92e0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
92f0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
9300: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
9310: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
9320: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
9330: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9340: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
9350: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
9360: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
9370: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
9380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
9390: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
93a0: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
93b0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
93c0: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  dy.  However, if
93d0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
93e0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
93f0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
9400: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
9410: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
9420: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
9430: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
9440: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
9450: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
9460: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
9470: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
9480: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
9490: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
94a0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
94b0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
94c0: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
94d0: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
94e0: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
94f0: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
9500: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
9510: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
9520: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
9530: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
9540: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
9550: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
9560: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
9570: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
9580: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
9590: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
95a0: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
95b0: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
95c0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
95d0: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
95e0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
95f0: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
9600: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
9610: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
9620: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
9630: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
9640: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9650: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
9660: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
9670: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
9680: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
9690: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
96a0: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
96b0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
96c0: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
96d0: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
96e0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
96f0: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
9700: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
9710: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
9720: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
9730: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
9740: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
9750: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
9760: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
9770: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
9780: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
9790: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
97a0: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
97b0: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
97c0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
97d0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
97e0: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
97f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
9800: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
9810: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
9820: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
9830: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
9840: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
9850: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
9860: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
9870: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
9880: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
9890: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
98a0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
98b0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
98c0: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
98d0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
98e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
98f0: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
9900: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
9910: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
9920: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
9930: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
9940: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
9950: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
9960: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
9970: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
9980: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
9990: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
99a0: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
99b0: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
99c0: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
99d0: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
99e0: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
99f0: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
9a00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
9a10: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
9a20: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
9a30: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
9a40: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
9a50: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
9a60: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
9a70: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
9a80: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
9a90: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
9aa0: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
9ab0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
9ac0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
9ad0: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
9ae0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
9af0: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
9b00: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
9b10: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
9b20: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
9b30: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
9b40: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
9b50: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
9b60: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
9b70: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
9b80: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
9b90: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9ba0: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
9bb0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9bc0: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
9bd0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
9be0: 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e  H14100} <S20000>
9bf0: 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45  <S30200>.** EXPE
9c00: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
9c10: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
9c20: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
9c30: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
9c40: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
9c50: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
9c60: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
9c70: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
9c80: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
9c90: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
9ca0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
9cb0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
9cc0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
9cd0: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
9ce0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
9cf0: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
9d00: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
9d10: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
9d20: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
9d30: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
9d40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
9d50: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
9d60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9d70: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
9d80: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
9d90: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
9da0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
9db0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
9dc0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
9dd0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
9de0: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
9df0: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
9e00: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9e10: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
9e20: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
9e30: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
9e40: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
9e50: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
9e60: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
9e70: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
9e80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9e90: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
9ea0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
9eb0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
9ec0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
9ed0: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  that sqlite3_con
9ee0: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
9ef0: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
9f00: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
9f10: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
9f20: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
9f30: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9f40: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
9f50: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
9f60: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9f70: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
9f80: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
9f90: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
9fa0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
9fb0: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
9fc0: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
9fd0: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
9fe0: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
9ff0: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
a000: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
a010: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
a020: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
a030: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
a040: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
a050: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
a060: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
a070: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20  t..**.** When a 
a080: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a090: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
a0a0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
a0b0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
a0c0: 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74  ]..** If the opt
a0d0: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
a0e0: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
a0f0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
a100: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
a110: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
a120: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
a130: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
a140: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
a150: 2a 20 5b 48 31 34 31 30 33 5d 20 5b 48 31 34 31  * [H14103] [H141
a160: 30 36 5d 20 5b 48 31 34 31 32 30 5d 20 5b 48 31  06] [H14120] [H1
a170: 34 31 32 33 5d 20 5b 48 31 34 31 32 36 5d 20 5b  4123] [H14126] [
a180: 48 31 34 31 32 39 5d 20 5b 48 31 34 31 33 32 5d  H14129] [H14132]
a190: 20 5b 48 31 34 31 33 35 5d 0a 2a 2a 20 5b 48 31   [H14135].** [H1
a1a0: 34 31 33 38 5d 20 5b 48 31 34 31 34 31 5d 20 5b  4138] [H14141] [
a1b0: 48 31 34 31 34 34 5d 20 5b 48 31 34 31 34 37 5d  H14144] [H14147]
a1c0: 20 5b 48 31 34 31 35 30 5d 20 5b 48 31 34 31 35   [H14150] [H1415
a1d0: 33 5d 20 5b 48 31 34 31 35 36 5d 20 5b 48 31 34  3] [H14156] [H14
a1e0: 31 35 39 5d 0a 2a 2a 20 5b 48 31 34 31 36 32 5d  159].** [H14162]
a1f0: 20 5b 48 31 34 31 36 35 5d 20 5b 48 31 34 31 36   [H14165] [H1416
a200: 38 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  8].*/.SQLITE_EXP
a210: 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71  ERIMENTAL int sq
a220: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
a230: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
a240: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
a250: 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
a260: 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32 30 30  ections  {H14200
a270: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
a280: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
a290: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
a2a0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
a2b0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
a2c0: 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
a2d0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
a2e0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
a2f0: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
a300: 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
a310: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
a320: 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
a330: 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
a340: 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
a350: 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
a360: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
a370: 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
a380: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
a390: 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
a3a0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
a3b0: 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20  erface can only 
a3c0: 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74  be used immediat
a3d0: 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65  ely after.** the
a3e0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a3f0: 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20  tion is created 
a400: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
a410: 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  pen()],.** [sqli
a420: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
a430: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
a440: 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  v2()].  .**.** T
a450: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
a460: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
a470: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
a480: 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66    is the.** conf
a490: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d  iguration verb -
a4a0: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
a4b0: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
a4c0: 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f  what.** aspect o
a4d0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
a4e0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
a4f0: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
a500: 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f  .** The only cho
a510: 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c  ice for this val
a520: 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42  ue is [SQLITE_DB
a530: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
a540: 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20  ]..** New verbs 
a550: 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65  are likely to be
a560: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
a570: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
a580: 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  ite..** Addition
a590: 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70  al arguments dep
a5a0: 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e  end on the verb.
a5b0: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
a5c0: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 32 30 33 5d  nts:.** [H14203]
a5d0: 20 5b 48 31 34 32 30 36 5d 20 5b 48 31 34 32 30   [H14206] [H1420
a5e0: 39 5d 20 5b 48 31 34 32 31 32 5d 20 5b 48 31 34  9] [H14212] [H14
a5f0: 32 31 35 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  215].*/.SQLITE_E
a600: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
a610: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
a620: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
a630: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
a640: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
a650: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
a660: 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c  tines {H10155} <
a670: 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52  S20120>.** EXPER
a680: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e  IMENTAL.**.** An
a690: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
a6a0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
a6b0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
a6c0: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
a6d0: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
a6e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
a6f0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
a700: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
a710: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
a720: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
a730: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
a740: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
a750: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
a760: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
a770: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
a780: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
a790: 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
a7a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
a7b0: 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
a7c0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
a7d0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
a7e0: 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
a7f0: 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
a800: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
a810: 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
a820: 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
a830: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
a840: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
a850: 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
a860: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
a870: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
a880: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
a890: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
a8a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
a8b0: 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
a8c0: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
a8d0: 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
a8e0: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
a8f0: 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
a900: 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
a910: 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
a920: 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
a930: 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
a940: 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
a950: 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
a960: 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
a970: 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
a980: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
a990: 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
a9a0: 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
a9b0: 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
a9c0: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
a9d0: 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
a9e0: 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
a9f0: 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
aa00: 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
aa10: 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
aa20: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
aa30: 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
aa40: 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
aa50: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
aa60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
aa70: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
aa80: 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
aa90: 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
aaa0: 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
aab0: 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
aac0: 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
aad0: 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
aae0: 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
aaf0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
ab00: 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  c and xFree meth
ab10: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
ab20: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
ab30: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
ab40: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
ab50: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
ab60: 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61  ary..** The xRea
ab70: 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74  lloc method must
ab80: 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c   work like reall
ab90: 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74  oc() from the st
aba0: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
abb0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63  .** with the exc
abc0: 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74  eption that if t
abd0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
abe0: 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69  nt to xRealloc i
abf0: 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c  s zero,.** xReal
ac00: 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f  loc must be a no
ac10: 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f  -op - it must no
ac20: 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c  t perform any al
ac30: 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64  location or.** d
ac40: 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 53 51  eallocation.  SQ
ac50: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 64 73  Lite guaranteeds
ac60: 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
ac70: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
ac80: 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
ac90: 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
aca0: 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
acb0: 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
acc0: 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61  .** And so in ca
acd0: 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64  ses where xRound
ace0: 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  up always return
acf0: 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d  s a positive num
ad00: 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  ber,.** xRealloc
ad10: 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61   can perform exa
ad20: 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e  ctly as the stan
ad30: 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61  dard library rea
ad40: 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74  lloc() and.** st
ad50: 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69  ill be in compli
ad60: 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73  ance with this s
ad70: 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a  pecification..**
ad80: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
ad90: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
ada0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
adb0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
adc0: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
add0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
ade0: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
adf0: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
ae00: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
ae10: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
ae20: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
ae30: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
ae40: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
ae50: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
ae60: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
ae70: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
ae80: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
ae90: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
aea0: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
aeb0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
aec0: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
aed0: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
aee0: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
aef0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
af00: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
af10: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
af20: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
af30: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
af40: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
af50: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
af60: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
af70: 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
af80: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
af90: 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
afa0: 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
afb0: 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
afc0: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
afd0: 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
afe0: 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
aff0: 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
b000: 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
b010: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
b020: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b030: 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
b040: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
b050: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
b060: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
b070: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
b080: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
b090: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
b0a0: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
b0b0: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
b0c0: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
b0d0: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
b0e0: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
b0f0: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
b100: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
b110: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
b120: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
b130: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
b140: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
b150: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
b160: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
b170: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
b180: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
b190: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
b1a0: 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
b1b0: 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
b1c0: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
b1d0: 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
b1e0: 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
b1f0: 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
b200: 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
b210: 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
b220: 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
b230: 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
b240: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
b250: 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
b260: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
b270: 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
b280: 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
b290: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
b2a0: 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
b2b0: 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
b2c0: 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
b2d0: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
b2e0: 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
b2f0: 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
b300: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
b310: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
b320: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b330: 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
b340: 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
b350: 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
b360: 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
b370: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
b380: 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
b390: 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
b3a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
b3b0: 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
b3c0: 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
b3d0: 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
b3e0: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
b3f0: 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
b400: 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
b410: 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
b420: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
b430: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
b440: 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
b450: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
b460: 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
b470: 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
b480: 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
b490: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
b4a0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b4b0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
b4c0: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
b4d0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b4e0: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
b4f0: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
b500: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
b510: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
b520: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
b530: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
b540: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
b550: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
b560: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
b570: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
b580: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
b590: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
b5a0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
b5b0: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
b5c0: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
b5d0: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
b5e0: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
b5f0: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
b600: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
b610: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
b620: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
b630: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
b640: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
b650: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
b660: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
b670: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
b680: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
b690: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
b6a0: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
b6b0: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
b6c0: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
b6d0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
b6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
b6f0: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
b700: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
b710: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
b720: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
b730: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
b740: 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30   {H10160} <S2000
b750: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
b760: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  AL.**.** These c
b770: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
b780: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
b790: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
b7a0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
b7b0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
b7c0: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
b7d0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
b7e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
b7f0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
b800: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
b810: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
b820: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
b830: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
b840: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
b850: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
b860: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
b870: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
b880: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
b890: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
b8a0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
b8b0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
b8c0: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
b8d0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
b8e0: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
b8f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b900: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
b910: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
b920: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
b930: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
b940: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
b950: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
b960: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
b970: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
b980: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
b990: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
b9a0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
b9b0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
b9c0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
b9d0: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
b9e0: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a  tion disables.**
b9f0: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
ba00: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
ba10: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
ba20: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
ba30: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
ba40: 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a  le thread.</dd>.
ba50: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
ba60: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
ba70: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
ba80: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
ba90: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
baa0: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74  ption.  This opt
bab0: 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20  ion disables.** 
bac0: 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
bad0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bae0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
baf0: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
bb00: 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
bb10: 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
bb20: 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
bb30: 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
bb40: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
bb50: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
bb60: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
bb70: 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
bb80: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
bb90: 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
bba0: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
bbb0: 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
bbc0: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
bbd0: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
bbe0: 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
bbf0: 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
bc00: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
bc10: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
bc20: 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
bc30: 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74  ame time.  See t
bc40: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
bc50: 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61  de].** documenta
bc60: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
bc70: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
bc80: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bc90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
bca0: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
bcb0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
bcc0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
bcd0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
bce0: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
bcf0: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
bd00: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
bd10: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
bd20: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
bd30: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
bd40: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
bd50: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
bd60: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
bd70: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
bd80: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
bd90: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
bda0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
bdb0: 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
bdc0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
bdd0: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
bde0: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
bdf0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
be00: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
be10: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
be20: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
be30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
be40: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
be50: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
be60: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
be70: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
be80: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
be90: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
bea0: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
beb0: 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65  time..** See the
bec0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
bed0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
bee0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
bef0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e  nformation.</dd>
bf00: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
bf10: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
bf20: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
bf30: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
bf40: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
bf50: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
bf60: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
bf70: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
bf80: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
bf90: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
bfa0: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
bfb0: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
bfc0: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
bfd0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bfe0: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
bff0: 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
c000: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
c010: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
c020: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
c030: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ite.</dd>.**.** 
c040: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c050: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
c060: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c070: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
c080: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
c090: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
c0a0: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
c0b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
c0c0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
c0d0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
c0e0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c0f0: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
c100: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
c110: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
c120: 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
c130: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c140: 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ..** This option
c150: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
c160: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
c170: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
c180: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
c190: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
c1a0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
c1b0: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
c1c0: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
c1d0: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
c1e0: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
c1f0: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ple.</dd>.**.** 
c200: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c210: 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
c220: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c230: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
c240: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
c250: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
c260: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
c270: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
c280: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
c290: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
c2a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c2b0: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
c2c0: 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64  s. When disabled
c2d0: 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
c2e0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c2f0: 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e  s become .** non
c300: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
c310: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
c320: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
c330: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
c340: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
c350: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
c360: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c370: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
c380: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  mit()].**   <li>
c390: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
c3a0: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a  ()].**   </ul>.*
c3b0: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
c3c0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c3d0: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
c3e0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c3f0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c400: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c410: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
c420: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
c430: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
c440: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
c450: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
c460: 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
c470: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
c480: 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
c490: 20 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f   the scrach allo
c4a0: 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
c4b0: 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
c4c0: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
c4d0: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
c4e0: 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
c4f0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
c500: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
c510: 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
c520: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
c530: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
c540: 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70   of 16. The sz p
c550: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
c560: 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a  be a few bytes.*
c570: 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  * larger than th
c580: 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68  e actual scratch
c590: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
c5a0: 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20  due to internal 
c5b0: 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65  overhead..** The
c5c0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
c5d0: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 20 74  should pointer t
c5e0: 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  o an 8-byte alig
c5f0: 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66  ned buffer.** of
c600: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
c610: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
c620: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  ** SQLite will u
c630: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
c640: 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
c650: 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74  er at once per t
c660: 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73  hread, so.** N s
c670: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
c680: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
c690: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
c6a0: 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a  hreads.  The sz.
c6b0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  ** parameter sho
c6c0: 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74  uld be 6 times t
c6d0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
c6e0: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
c6f0: 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63  page size..** Sc
c700: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72  ratch buffers ar
c710: 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f  e used as part o
c720: 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61  f the btree bala
c730: 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  nce operation.  
c740: 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20  If.** The btree 
c750: 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61  balancer needs a
c760: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79  dditional memory
c770: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
c780: 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73  provided by.** s
c790: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f  cratch buffers o
c7a0: 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20  r if no scratch 
c7b0: 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20  buffer space is 
c7c0: 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
c7d0: 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74  SQLite.** goes t
c7e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
c7f0: 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74  c()] to obtain t
c800: 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65  he memory it nee
c810: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ds.</dd>.**.** <
c820: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c830: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
c840: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c850: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
c860: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
c870: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
c880: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
c890: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
c8a0: 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
c8b0: 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
c8c0: 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e  he implemenation
c8d0: 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
c8e0: 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
c8f0: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
c900: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
c910: 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
c920: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
c930: 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
c940: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
c950: 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69  NFIG_PCACHE opti
c960: 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
c970: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
c980: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
c990: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
c9a0: 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
c9b0: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
c9c0: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
c9d0: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
c9e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
c9f0: 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
ca00: 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
ca10: 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
ca20: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
ca30: 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
ca40: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
ca50: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
ca60: 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
ca70: 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
ca80: 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
ca90: 2e 20 20 54 68 65 20 70 61 67 65 20 68 65 61 64  .  The page head
caa0: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
cab0: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
cac0: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
cad0: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
cae0: 20 20 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73    It is harmless
caf0: 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
cb00: 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
cb10: 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
cb20: 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
cb30: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
cb40: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
cb50: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
cb60: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
cb70: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
cb80: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69   memory..** SQLi
cb90: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
cba0: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
cbb0: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
cbc0: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
cbd0: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
cbe0: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
cbf0: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
cc00: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
cc10: 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  .  If additional
cc20: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
cc30: 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
cc40: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
cc50: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
cc60: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
cc70: 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
cc80: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
cc90: 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
cca0: 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
ccb0: 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  ce..** The imple
ccc0: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
ccd0: 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  use one or more 
cce0: 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73  of the N buffers
ccf0: 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d   to hold .** mem
cd00: 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
cd10: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20  nformation. The 
cd20: 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
cd30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
cd40: 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
cd50: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
cd60: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
cd70: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
cd80: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
cd90: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
cda0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cdb0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
cdc0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
cdd0: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
cde0: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
cdf0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
ce00: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
ce10: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
ce20: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
ce30: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
ce40: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
ce50: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
ce60: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
ce70: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
ce80: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
ce90: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
cea0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
ceb0: 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
cec0: 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
ced0: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
cee0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
cef0: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
cf00: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
cf10: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
cf20: 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 49  ation size..** I
cf30: 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
cf40: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
cf50: 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
cf60: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
cf70: 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
cf80: 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
cf90: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
cfa0: 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
cfb0: 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
cfc0: 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
cfd0: 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
cfe0: 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
cff0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
d000: 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72   If the.** memor
d010: 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
d020: 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
d030: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
d040: 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
d050: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
d060: 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
d070: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
d080: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
d090: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
d0a0: 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
d0b0: 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
d0c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d0d0: 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
d0e0: 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
d0f0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
d100: 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
d110: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
d120: 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
d130: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
d140: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
d150: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
d160: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d170: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
d180: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
d190: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d1a0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
d1b0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
d1c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
d1d0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d1e0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
d1f0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
d200: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
d210: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
d220: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
d230: 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
d240: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
d250: 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75   place.** the mu
d260: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
d270: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c  lt into SQLite.<
d280: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d290: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d2a0: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
d2b0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
d2c0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
d2d0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
d2e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
d2f0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
d300: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
d310: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
d320: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
d330: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
d340: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
d350: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
d360: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
d370: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
d380: 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f  tines..** This o
d390: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
d3a0: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
d3b0: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
d3c0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
d3d0: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
d3e0: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
d3f0: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
d400: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
d410: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
d420: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
d430: 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  mple.</dd>.**.**
d440: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d450: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
d460: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
d470: 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
d480: 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
d490: 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
d4a0: 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
d4b0: 6c 6f 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69  location lookasi
d4c0: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  de optimization.
d4d0: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
d4e0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
d4f0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
d500: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
d510: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
d520: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
d530: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
d540: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
d550: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d560: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  .  This option s
d570: 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
d580: 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
d590: 69 64 65 20 73 69 7a 65 2e 20 20 54 68 65 20 5b  ide size.  The [
d5a0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
d5b0: 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
d5c0: 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
d5d0: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
d5e0: 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
d5f0: 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
d600: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
d610: 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
d620: 6f 6e 6e 65 63 74 69 6f 6e 73 2e 3c 2f 64 64 3e  onnections.</dd>
d630: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
d640: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c  E_CONFIG_PCACHE<
d650: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
d660: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
d670: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
d680: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
d690: 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c  er to.** an [sql
d6a0: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
d6b0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ods] object.  Th
d6c0: 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
d6d0: 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
d6e0: 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
d6f0: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
d700: 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c  ementation.  SQL
d710: 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
d720: 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
d730: 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
d740: 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
d750: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
d760: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d770: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d780: 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  TPCACHE</dt>.** 
d790: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
d7a0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
d7b0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
d7c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
d7d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
d7e0: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
d7f0: 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
d800: 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
d810: 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
d820: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d830: 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
d840: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64  .</dd>.**.** </d
d850: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
d860: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
d870: 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
d880: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
d890: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
d8a0: 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
d8b0: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
d8c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
d8d0: 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
d8e0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
d8f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
d900: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
d910: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
d920: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
d930: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
d940: 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
d950: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
d960: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
d970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d980: 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
d990: 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
d9a0: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
d9b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d9c0: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
d9d0: 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
d9e0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
d9f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
da00: 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
da10: 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
da20: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
da30: 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
da40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
da50: 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
da60: 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
da70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
da80: 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
da90: 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
daa0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
dab0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dac0: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
dad0: 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
dae0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
daf0: 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
db00: 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
db10: 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
db20: 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
db30: 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
db40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
db50: 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
db60: 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
db70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
db80: 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
db90: 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  14  /* sqlite3_p
dba0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
dbb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dbc0: 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
dbd0: 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69  E    15  /* sqli
dbe0: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
dbf0: 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ds* */../*.** CA
dc00: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
dc10: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48  ation Options {H
dc20: 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10170} <S20000>.
dc30: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
dc40: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
dc50: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
dc60: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
dc70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
dc80: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
dc90: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
dca0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
dcb0: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
dcc0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
dcd0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
dce0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
dcf0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
dd00: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
dd10: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
dd20: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
dd30: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
dd40: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
dd50: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
dd60: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
dd70: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
dd80: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
dd90: 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
dda0: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
ddb0: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
ddc0: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
ddd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
dde0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
ddf0: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
de00: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
de10: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
de20: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
de30: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
de40: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
de50: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
de60: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
de70: 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
de80: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
de90: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
dea0: 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
deb0: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
dec0: 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
ded0: 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
dee0: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
def0: 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
df00: 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
df10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
df20: 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  on]..** The firs
df30: 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
df40: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
df50: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
df60: 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
df70: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d   pointer to an m
df80: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
df90: 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
dfa0: 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 54 68 65  e memory..** The
dfb0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
dfc0: 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
dfd0: 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
dfe0: 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
dff0: 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
e000: 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
e010: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
e020: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63  loc()].  The sec
e030: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
e040: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
e050: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
e060: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
e070: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
e080: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
e090: 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
e0a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
e0b0: 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
e0c0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
e0d0: 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
e0e0: 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
e0f0: 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
e100: 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
e110: 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
e120: 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
e130: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
e140: 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
e150: 79 2e 20 20 49 66 20 74 68 65 20 73 65 63 6f 6e  y.  If the secon
e160: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 6f  d argument is no
e170: 74 0a 2a 2a 20 61 20 6d 75 6c 74 69 70 6c 65 20  t.** a multiple 
e180: 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
e190: 72 6e 61 6c 6c 79 20 72 6f 75 6e 64 65 64 20 64  rnally rounded d
e1a0: 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
e1b0: 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69  smaller.** multi
e1c0: 70 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20 61  ple of 8.  See a
e1d0: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  lso: [SQLITE_CON
e1e0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f  FIG_LOOKASIDE]</
e1f0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
e200: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e210: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
e220: 53 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a  SIDE    1001  /*
e230: 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
e240: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
e250: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
e260: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
e270: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32  esult Codes {H12
e280: 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  200} <S10700>.**
e290: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e2a0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
e2b0: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
e2c0: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
e2d0: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
e2e0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
e2f0: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
e300: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64  Lite. The extend
e310: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
e320: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
e330: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
e340: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
e350: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72  ibility consider
e360: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  ations..**.** Re
e370: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
e380: 48 31 32 32 30 31 5d 20 5b 48 31 32 32 30 32 5d  H12201] [H12202]
e390: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
e3a0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
e3b0: 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
e3c0: 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
e3d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
e3e0: 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b  t Insert Rowid {
e3f0: 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e  H12220} <S10700>
e400: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72  .**.** Each entr
e410: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
e420: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
e430: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
e440: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
e450: 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
e460: 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65   | "rowid"]. The
e470: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
e480: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
e490: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
e4a0: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
e4b0: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
e4c0: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
e4d0: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
e4e0: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
e4f0: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
e500: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49  lared columns. I
e510: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
e520: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
e530: 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
e540: 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
e550: 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
e560: 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
e570: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
e580: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
e590: 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
e5a0: 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
e5b0: 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
e5c0: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
e5d0: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
e5e0: 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
e5f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
e600: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
e610: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f  argument.  If no
e620: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
e630: 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
e640: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
e650: 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
e660: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
e670: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
e680: 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20   If an [INSERT] 
e690: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
e6a0: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
e6b0: 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
e6c0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
e6d0: 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
e6e0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20  this routine as 
e6f0: 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
e700: 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ger is running..
e710: 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
e720: 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74  trigger terminat
e730: 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  es, the value re
e740: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
e750: 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74  outine.** revert
e760: 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61  s to the last va
e770: 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66  lue inserted bef
e780: 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
e790: 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  fired..**.** An 
e7a0: 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
e7b0: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
e7c0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
e7d0: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
e7e0: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
e7f0: 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
e800: 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
e810: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
e820: 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  .** routine.  Th
e830: 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
e840: 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
e850: 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
e860: 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
e870: 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
e880: 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
e890: 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
e8a0: 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
e8b0: 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
e8c0: 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
e8d0: 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20  s.  When INSERT 
e8e0: 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
e8f0: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
e900: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
e910: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
e920: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
e930: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
e940: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
e950: 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
e960: 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
e970: 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
e980: 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
e990: 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
e9a0: 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
e9b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
e9c0: 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
e9d0: 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  e..**.** For the
e9e0: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
e9f0: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
ea00: 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
ea10: 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
ea20: 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
ea30: 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
ea40: 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
ea50: 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
ea60: 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 32 31 5d  nts:.** [H12221]
ea70: 20 5b 48 31 32 32 32 33 5d 0a 2a 2a 0a 2a 2a 20   [H12223].**.** 
ea80: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
ea90: 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
eaa0: 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
eab0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
eac0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
ead0: 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
eae0: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
eaf0: 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
eb00: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
eb10: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
eb20: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
eb30: 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
eb40: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
eb50: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
eb60: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
eb70: 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
eb80: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
eb90: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
eba0: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
ebb0: 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
ebc0: 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
ebd0: 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
ebe0: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
ebf0: 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
ec00: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
ec10: 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
ec20: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
ec30: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d  odified {H12240}
ec40: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
ec50: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
ec60: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
ec70: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
ec80: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
ec90: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
eca0: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
ecb0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
ecc0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
ecd0: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
ece0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
ecf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
ed00: 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
ed10: 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
ed20: 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
ed30: 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
ed40: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
ed50: 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
ed60: 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
ed70: 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
ed80: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
ed90: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
eda0: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
edb0: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
edc0: 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
edd0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
ede0: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
edf0: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
ee00: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
ee10: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
ee20: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
ee30: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
ee40: 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76  * Changes to a v
ee50: 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
ee60: 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
ee70: 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
ee80: 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
ee90: 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
eea0: 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
eeb0: 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
eec0: 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
eed0: 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
eee0: 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
eef0: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
ef00: 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
ef10: 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
ef20: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
ef30: 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
ef40: 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
ef50: 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
ef60: 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
ef70: 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
ef80: 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
ef90: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
efa0: 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
efb0: 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
efc0: 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
efd0: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
efe0: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
eff0: 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
f000: 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
f010: 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
f020: 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
f030: 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
f040: 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
f050: 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
f060: 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
f070: 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
f080: 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
f090: 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
f0a0: 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
f0b0: 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
f0c0: 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
f0d0: 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
f0e0: 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
f0f0: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
f100: 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
f110: 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
f120: 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
f130: 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
f140: 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
f150: 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
f160: 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
f170: 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
f180: 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  n..**.** Calling
f190: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
f1a0: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
f1b0: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
f1c0: 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
f1d0: 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
f1e0: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
f1f0: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
f200: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
f210: 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
f220: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
f230: 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
f240: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
f250: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
f260: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
f270: 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
f280: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75  ntext..**.** Thu
f290: 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
f2a0: 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
f2b0: 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
f2c0: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
f2d0: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
f2e0: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
f2f0: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
f300: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
f310: 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
f320: 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
f330: 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74  level.  Within t
f340: 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
f350: 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
f360: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
f370: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
f380: 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
f390: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
f3a0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
f3b0: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
f3c0: 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
f3d0: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
f3e0: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
f3f0: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
f400: 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
f410: 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
f420: 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
f430: 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
f440: 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
f450: 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
f460: 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
f470: 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
f480: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53  context..**.** S
f490: 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
f4a0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
f4b0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
f4c0: 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  and the.** [coun
f4d0: 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
f4e0: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
f4f0: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 34  ments:.** [H1224
f500: 31 5d 20 5b 48 31 32 32 34 33 5d 0a 2a 2a 0a 2a  1] [H12243].**.*
f510: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
f520: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
f530: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
f540: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f550: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
f560: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
f570: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
f580: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
f590: 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
f5a0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
f5b0: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
f5c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
f5d0: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
f5e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f5f0: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
f600: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48  Rows Modified {H
f610: 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a  12260} <S10600>.
f620: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
f630: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
f640: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
f650: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
f660: 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
f670: 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
f680: 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
f690: 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
f6a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
f6b0: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20   opened..** The 
f6c0: 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61  count includes a
f6d0: 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20  ll changes from 
f6e0: 61 6c 6c 20 0a 2a 2a 20 5b 43 52 45 41 54 45 20  all .** [CREATE 
f6f0: 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
f700: 72 5d 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f  r] contexts.  Ho
f710: 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
f720: 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
f730: 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
f740: 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
f750: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
f760: 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
f770: 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
f780: 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
f790: 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
f7a0: 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
f7b0: 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
f7c0: 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
f7d0: 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
f7e0: 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
f7f0: 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
f800: 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
f810: 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
f820: 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
f830: 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
f840: 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
f850: 65 64 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ed..** The chang
f860: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  es are counted a
f870: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74  s soon as the st
f880: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
f890: 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f  es them is.** co
f8a0: 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
f8b0: 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
f8c0: 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  le is passed to 
f8d0: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
f8e0: 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
f8f0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
f900: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
f910: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
f920: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
f930: 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  and the.** [coun
f940: 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
f950: 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
f960: 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 36  ments:.** [H1226
f970: 31 5d 20 5b 48 31 32 32 36 33 5d 0a 2a 2a 0a 2a  1] [H12263].**.*
f980: 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
f990: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
f9a0: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
f9b0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f9c0: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
f9d0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
f9e0: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
f9f0: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
fa00: 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
fa10: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
fa20: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
fa30: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
fa40: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
fa50: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
fa60: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
fa70: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
fa80: 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32  ning Query {H122
fa90: 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a  70} <S30500>.**.
faa0: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
fab0: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
fac0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
fad0: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
fae0: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
faf0: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
fb00: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
fb10: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
fb20: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
fb30: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
fb40: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
fb50: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
fb60: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
fb70: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
fb80: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
fb90: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
fba0: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
fbb0: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
fbc0: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
fbd0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
fbe0: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
fbf0: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
fc00: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
fc10: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
fc20: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
fc30: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
fc40: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
fc50: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
fc60: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
fc70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fc80: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
fc90: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
fca0: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
fcb0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
fcc0: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
fcd0: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
fce0: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
fcf0: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
fd00: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
fd10: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
fd20: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
fd30: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
fd40: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
fd50: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
fd60: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
fd70: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
fd80: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
fd90: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
fda0: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
fdb0: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
fdc0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
fdd0: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  PT]..** If the i
fde0: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
fdf0: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
fe00: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
fe10: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
fe20: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
fe30: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
fe40: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
fe50: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
fe60: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
fe70: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
fe80: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ally..**.** The 
fe90: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
fea0: 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
feb0: 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
fec0: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
fed0: 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
fee0: 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
fef0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
ff00: 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20 6e  complete.  Any n
ff10: 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
ff20: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
ff30: 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
ff40: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ff50: 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
ff60: 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
ff70: 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
ff80: 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
ff90: 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
ffa0: 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
ffb0: 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
ffc0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
ffd0: 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
ffe0: 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74 65  .  New SQL state
fff0: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
10000 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
10010 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
10020 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
10030 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
10040 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
10050 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
10060 72 72 75 70 74 28 29 2e 0a 2a 2a 20 41 20 63 61  rrupt()..** A ca
10070 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
10080 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
10090 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
100a0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
100b0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
100c0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
100d0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
100e0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
100f0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
10100 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
10110 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
10120 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
10130 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
10140 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 37 31  ents:.** [H12271
10150 5d 20 5b 48 31 32 32 37 32 5d 0a 2a 2a 0a 2a 2a  ] [H12272].**.**
10160 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
10170 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
10180 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
10190 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
101a0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
101b0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
101c0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
101d0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
101e0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
101f0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
10200 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
10210 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
10220 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
10230 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30   {H10510} <S7020
10240 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
10250 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
10260 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
10270 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
10280 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
10290 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
102a0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
102b0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
102c0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
102d0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
102e0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
102f0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
10300 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
10310 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
10320 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65   parsing.  These
10330 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
10340 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
10350 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
10360 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
10370 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
10380 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69  .  A statement i
10390 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
103a0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
103b0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
103c0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
103d0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
103e0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
103f0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
10400 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
10410 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
10420 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
10430 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
10440 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
10450 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
10460 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
10470 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
10480 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
10490 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
104a0 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
104b0 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
104c0 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
104d0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
104e0 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
104f0 69 6e 61 74 6f 72 2e 20 20 57 68 69 74 65 73 70  inator.  Whitesp
10500 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
10510 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
10520 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
10530 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
10540 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
10550 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
10560 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
10570 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
10580 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
10590 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
105a0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
105b0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
105c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
105d0 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
105e0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
105f0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
10600 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
10610 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
10620 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
10630 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
10640 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
10650 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
10660 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
10670 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
10680 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
10690 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
106a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
106b0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
106c0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
106d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
106e0 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
106f0 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
10700 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
10710 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
10720 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
10730 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
10740 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
10750 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
10760 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
10770 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
10780 6d 70 6c 65 74 65 2e 0a 2a 2a 0a 2a 2a 20 52 65  mplete..**.** Re
10790 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30  quirements: [H10
107a0 35 31 31 5d 20 5b 48 31 30 35 31 32 5d 0a 2a 2a  511] [H10512].**
107b0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
107c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
107d0 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
107e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
107f0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
10800 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
10810 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
10820 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
10830 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
10840 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
10850 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
10860 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
10870 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
10880 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
10890 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
108a0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
108b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
108c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
108d0 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
108e0 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
108f0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
10900 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30   {H12310} <S4040
10910 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
10920 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
10930 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
10940 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
10950 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
10960 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
10970 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
10980 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
10990 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
109a0 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
109b0 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
109c0 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
109d0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
109e0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
109f0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
10a00 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
10a10 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
10a20 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
10a30 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
10a40 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63  k. If the busy c
10a50 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
10a60 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
10a70 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
10a80 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
10a90 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
10aa0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
10ab0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61  gument to the ha
10ac0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
10ad0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
10ae0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
10af0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
10b00 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
10b10 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
10b20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
10b30 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61  ent to.** the ha
10b40 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
10b50 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
10b60 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
10b70 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
10b80 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
10b90 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
10ba0 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a   event.  If the.
10bb0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
10bc0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
10bd0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
10be0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
10bf0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
10c00 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
10c10 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
10c20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
10c30 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
10c40 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
10c50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
10c60 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
10c70 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
10c80 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
10c90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
10ca0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
10cb0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
10cc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
10cd0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
10ce0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
10cf0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
10d00 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
10d10 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
10d20 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
10d30 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74  n. If SQLite det
10d40 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
10d50 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
10d60 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
10d70 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
10d80 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
10d90 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
10da0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
10db0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
10dc0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
10dd0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
10de0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
10df0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
10e00 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
10e10 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
10e20 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
10e30 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
10e40 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
10e50 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
10e60 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
10e70 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
10e80 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
10e90 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
10ea0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
10eb0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
10ec0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
10ed0 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
10ee0 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
10ef0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
10f00 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
10f10 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
10f20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
10f30 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
10f40 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
10f50 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
10f60 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
10f70 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
10f80 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
10f90 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
10fa0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
10fb0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
10fc0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
10fd0 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
10fe0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
10ff0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
11000 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
11010 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
11020 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
11030 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
11040 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
11050 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
11060 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
11070 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
11080 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
11090 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
110a0 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
110b0 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
110c0 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
110d0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
110e0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
110f0 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
11100 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
11110 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
11120 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
11130 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
11140 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
11150 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
11160 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
11170 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
11180 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
11190 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
111a0 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
111b0 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
111c0 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
111d0 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
111e0 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
111f0 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
11200 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
11210 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
11220 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69  * readers.  If i
11230 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
11240 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
11250 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
11260 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
11270 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
11280 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
11290 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
112a0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
112b0 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
112c0 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
112d0 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
112e0 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
112f0 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
11300 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
11310 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
11320 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
11330 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
11340 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
11350 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
11360 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
11370 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
11380 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
11390 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
113a0 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
113b0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
113c0 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
113d0 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
113e0 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
113f0 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
11400 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
11410 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
11420 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
11430 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
11440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11450 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
11460 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
11470 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
11480 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
11490 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  ler.  Note that 
114a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
114b0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
114c0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
114d0 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
114e0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
114f0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
11500 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
11510 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
11520 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
11530 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
11540 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
11550 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
11560 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
11570 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
11580 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
11590 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
115a0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
115b0 2a 2a 20 5b 48 31 32 33 31 31 5d 20 5b 48 31 32  ** [H12311] [H12
115c0 33 31 32 5d 20 5b 48 31 32 33 31 34 5d 20 5b 48  312] [H12314] [H
115d0 31 32 33 31 36 5d 20 5b 48 31 32 33 31 38 5d 0a  12316] [H12318].
115e0 2a 2a 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  **.** A busy han
115f0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
11600 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
11610 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
11620 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
11630 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
11640 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
11650 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
11660 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
11670 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
11680 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
11690 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
116a0 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
116b0 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33  sy Timeout {H123
116c0 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a  40} <S40410>.**.
116d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
116e0 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
116f0 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
11700 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
11710 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
11720 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
11730 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
11740 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
11750 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a  d.  The handler.
11760 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
11770 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
11780 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
11790 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
117a0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
117b0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b  e accumulated. {
117c0 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d  H12343} After "m
117d0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
117e0 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
117f0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
11800 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
11810 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
11820 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
11830 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
11840 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
11850 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
11860 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
11870 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
11880 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
11890 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
118a0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
118b0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
118c0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
118d0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
118e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
118f0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
11900 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11910 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
11920 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
11930 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
11940 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
11950 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
11960 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
11970 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
11980 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
11990 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
119a0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
119b0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a  er is cleared..*
119c0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
119d0 73 3a 0a 2a 2a 20 5b 48 31 32 33 34 31 5d 20 5b  s:.** [H12341] [
119e0 48 31 32 33 34 33 5d 20 5b 48 31 32 33 34 34 5d  H12343] [H12344]
119f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
11a00 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
11a10 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
11a20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11a30 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
11a40 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
11a50 67 20 51 75 65 72 69 65 73 20 7b 48 31 32 33 37  g Queries {H1237
11a60 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S10000>.**.*
11a70 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
11a80 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
11a90 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
11aa0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
11ab0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
11ac0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11ad0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
11ae0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
11af0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
11b00 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
11b10 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
11b20 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
11b30 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
11b40 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
11b50 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
11b60 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
11b70 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
11b80 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
11b90 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
11ba0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
11bb0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
11bc0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
11bd0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
11be0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
11bf0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
11c00 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
11c10 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
11c20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
11c30 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
11c40 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
11c50 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
11c60 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
11c70 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
11c80 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
11c90 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
11ca0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
11cb0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
11cc0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
11cd0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
11ce0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
11cf0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
11d00 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
11d10 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
11d20 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
11d30 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
11d40 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
11d50 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
11d60 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
11d70 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
11d80 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
11d90 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
11da0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
11db0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
11dc0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
11dd0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
11de0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
11df0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
11e00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
11e10 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
11e20 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
11e30 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
11e40 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
11e50 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
11e60 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
11e70 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
11e80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
11e90 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
11ea0 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
11eb0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
11ec0 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
11ed0 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
11ee0 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
11ef0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
11f00 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
11f10 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
11f20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
11f30 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
11f40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
11f50 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
11f60 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
11f70 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
11f80 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
11f90 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
11fa0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
11fb0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
11fc0 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
11fd0 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
11fe0 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
11ff0 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
12000 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
12010 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
12020 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
12030 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
12040 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
12050 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
12060 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
12070 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
12080 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
12090 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
120a0 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
120b0 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
120c0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
120d0 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
120e0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
120f0 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
12100 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
12110 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
12120 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12130 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
12140 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
12150 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
12160 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
12170 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
12180 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
12190 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
121a0 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
121b0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
121c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
121d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
121e0 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
121f0 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
12200 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
12210 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
12220 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
12230 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
12240 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
12250 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
12260 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ter.  It returns
12270 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
12280 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
12290 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
122a0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
122b0 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61  .** After the ca
122c0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68  lling function h
122d0 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
122e0 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74  g the result, it
122f0 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20   should.** pass 
12300 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
12310 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
12320 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
12330 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
12340 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
12350 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
12360 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
12370 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
12380 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
12390 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
123a0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
123b0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
123c0 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
123d0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
123e0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
123f0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
12400 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
12410 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
12420 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
12430 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
12440 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
12450 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
12460 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
12470 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
12480 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
12490 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
124a0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
124b0 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
124c0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
124d0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
124e0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
124f0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
12500 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
12510 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
12520 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
12530 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
12540 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
12550 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
12560 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
12570 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
12580 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
12590 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
125a0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
125b0 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
125c0 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
125d0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
125e0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
125f0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20  3_errcode()] or 
12600 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
12610 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
12620 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33  ements:.** [H123
12630 37 31 5d 20 5b 48 31 32 33 37 33 5d 20 5b 48 31  71] [H12373] [H1
12640 32 33 37 34 5d 20 5b 48 31 32 33 37 36 5d 20 5b  2374] [H12376] [
12650 48 31 32 33 37 39 5d 20 5b 48 31 32 33 38 32 5d  H12379] [H12382]
12660 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12670 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
12680 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
12690 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
126a0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
126b0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
126c0 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
126d0 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
126e0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
126f0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
12700 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
12710 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
12720 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
12730 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
12740 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
12750 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
12760 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
12770 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
12780 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
12790 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
127a0 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
127b0 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
127c0 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
127d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
127e0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
127f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
12800 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
12810 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
12820 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30  unctions {H17400
12830 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30  } <S70000><S2000
12840 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
12850 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
12860 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
12870 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
12880 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
12890 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
128a0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
128b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
128c0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
128d0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
128e0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
128f0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
12900 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
12910 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
12920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
12930 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
12940 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
12950 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
12960 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
12970 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
12980 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f  ree()].  Both ro
12990 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
129a0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
129b0 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
129c0 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
129d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
129e0 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
129f0 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
12a00 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
12a10 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   In sqlite3_snpr
12a20 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
12a30 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
12a40 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
12a50 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
12a60 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
12a70 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
12a80 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
12a90 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
12aa0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
12ab0 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
12ac0 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
12ad0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12ae0 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
12af0 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
12b00 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
12b10 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
12b20 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
12b30 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  ().  This is an.
12b40 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
12b50 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
12b60 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
12b70 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
12b80 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
12b90 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61  ibility.  Note a
12ba0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
12bb0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
12bc0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
12bd0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
12be0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
12bf0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
12c00 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
12c10 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
12c20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69  buffer.  We admi
12c30 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
12c40 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
12c50 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
12c60 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
12c70 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
12c80 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
12c90 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
12ca0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
12cb0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
12cc0 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
12cd0 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
12ce0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  ility..**.** As 
12cf0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
12d00 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
12d10 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
12d20 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
12d30 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
12d40 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
12d50 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
12d60 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66  rminated.  The f
12d70 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
12d80 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
12d90 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
12da0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
12db0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
12dc0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
12dd0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
12de0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
12df0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
12e00 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
12e10 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
12e20 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
12e30 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
12e40 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
12e50 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
12e60 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
12e70 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
12e80 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
12e90 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
12ea0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
12eb0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
12ec0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
12ed0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
12ee0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
12ef0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
12f00 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
12f10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
12f20 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
12f30 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
12f40 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
12f50 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
12f60 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
12f70 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
12f80 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
12f90 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
12fa0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
12fb0 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
12fc0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
12fd0 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
12fe0 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
12ff0 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
13000 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
13010 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
13020 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
13030 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
13040 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
13050 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
13060 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
13070 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
13080 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
13090 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
130a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
130b0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
130c0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
130d0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
130e0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
130f0 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
13100 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
13110 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
13120 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
13130 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
13140 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
13150 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
13160 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
13170 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
13180 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
13190 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
131a0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
131b0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
131c0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
131d0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
131e0 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
131f0 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
13200 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
13210 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
13220 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
13230 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
13240 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
13250 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
13260 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
13270 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
13280 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
13290 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
132a0 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
132b0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
132c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
132d0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
132e0 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
132f0 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
13300 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
13310 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
13320 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
13330 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
13340 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
13350 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
13360 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
13370 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
13380 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
13390 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
133a0 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
133b0 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
133c0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
133d0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
133e0 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
133f0 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
13400 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
13410 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
13420 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ral..**.** The %
13430 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
13440 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
13450 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
13460 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
13470 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
13480 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
13490 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
134a0 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
134b0 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
134c0 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
134d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
134e0 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
134f0 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
13500 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
13510 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
13520 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
13530 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  on.  So, for exa
13540 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
13550 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
13560 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
13570 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
13580 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
13590 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
135a0 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
135b0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
135c0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
135d0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
135e0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
135f0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
13600 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
13610 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
13620 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
13630 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
13640 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
13650 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
13660 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
13670 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
13680 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
13690 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
136a0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
136b0 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
136c0 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
136d0 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
136e0 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
136f0 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
13700 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
13710 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
13720 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
13730 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
13740 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
13750 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
13760 74 73 3a 0a 2a 2a 20 5b 48 31 37 34 30 33 5d 20  ts:.** [H17403] 
13770 5b 48 31 37 34 30 36 5d 20 5b 48 31 37 34 30 37  [H17406] [H17407
13780 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ].*/.char *sqlit
13790 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
137a0 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
137b0 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
137c0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
137d0 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
137e0 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
137f0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
13800 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
13810 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13820 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
13830 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37  n Subsystem {H17
13840 33 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  300} <S20000>.**
13850 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
13860 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20  ore  uses these 
13870 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
13880 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
13890 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
138a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
138b0 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
138c0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
138d0 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
138e0 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
138f0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
13900 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
13910 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
13920 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
13930 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
13940 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
13950 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
13960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
13970 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
13980 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
13990 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
139a0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
139b0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
139c0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
139d0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
139e0 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ter..** If sqlit
139f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
13a00 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
13a10 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
13a20 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
13a30 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
13a40 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61  nter.  If the pa
13a50 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
13a60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13a70 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
13a80 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
13a90 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
13aa0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
13ab0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  nter..**.** Call
13ac0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
13ad0 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
13ae0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
13af0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
13b00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
13b10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
13b20 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
13b30 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
13b40 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
13b50 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  used.  The sqlit
13b60 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
13b70 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
13b80 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
13b90 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
13ba0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
13bb0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
13bc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
13bd0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
13be0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
13bf0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
13c00 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
13c10 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
13c20 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
13c30 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
13c40 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
13c50 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
13c60 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
13c70 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
13c80 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
13c90 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
13ca0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
13cb0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
13cc0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
13cd0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
13ce0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
13cf0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
13d00 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
13d10 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
13d20 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
13d30 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
13d40 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
13d50 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
13d60 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
13d70 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
13d80 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
13d90 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
13da0 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
13db0 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
13dc0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
13dd0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
13de0 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
13df0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
13e00 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
13e10 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  t.** parameter. 
13e20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
13e30 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
13e40 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
13e50 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
13e60 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
13e70 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
13e80 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
13e90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
13ea0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
13eb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13ec0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
13ed0 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65  loc()..** If the
13ee0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13ef0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
13f00 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
13f10 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
13f20 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
13f30 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
13f40 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
13f50 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
13f60 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
13f70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13f80 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
13f90 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65  loc()..** sqlite
13fa0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
13fb0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
13fc0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
13fd0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
13fe0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
13ff0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
14000 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
14010 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
14020 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20  .** If M is the 
14030 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
14040 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
14050 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
14060 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
14070 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
14080 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
14090 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
140a0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
140b0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
140c0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
140d0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
140e0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73  s freed..** If s
140f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14100 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
14110 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
14120 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
14130 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
14140 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
14150 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
14160 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
14170 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
14180 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
14190 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
141a0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
141b0 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  y. {END}.**.** T
141c0 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65  he default imple
141d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
141e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
141f0 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
14200 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28  s.** the malloc(
14210 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
14220 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
14230 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
14240 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b   C library..** {
14250 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c  H17382} However,
14260 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
14270 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
14280 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59  ** SQLITE_MEMORY
14290 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e  _SIZE=<i>NNN</i>
142a0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
142b0 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e  macro (where <i>
142c0 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e  NNN</i>.** is an
142d0 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20   integer), then 
142e0 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20  SQLite create a 
142f0 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20  static array of 
14300 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e  at least.** <i>N
14310 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20  NN</i> bytes in 
14320 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68  size and uses th
14330 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c  at array for all
14340 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a   of its dynamic.
14350 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
14360 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44  tion needs. {END
14370 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  }  Additional me
14380 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
14390 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65  ptions.** may be
143a0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
143b0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
143c0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
143d0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
143e0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
143f0 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
14400 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
14410 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
14420 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
14430 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
14440 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
14450 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
14460 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
14470 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
14480 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
14490 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
144a0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
144b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
144c0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
144d0 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
144e0 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
144f0 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
14500 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
14510 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
14520 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
14530 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
14540 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
14550 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
14560 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
14570 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
14580 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
14590 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
145a0 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
145b0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
145c0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
145d0 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
145e0 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
145f0 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
14600 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
14610 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
14620 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
14630 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
14640 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
14650 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
14660 2a 2a 20 5b 48 31 37 33 30 33 5d 20 5b 48 31 37  ** [H17303] [H17
14670 33 30 34 5d 20 5b 48 31 37 33 30 35 5d 20 5b 48  304] [H17305] [H
14680 31 37 33 30 36 5d 20 5b 48 31 37 33 31 30 5d 20  17306] [H17310] 
14690 5b 48 31 37 33 31 32 5d 20 5b 48 31 37 33 31 35  [H17312] [H17315
146a0 5d 20 5b 48 31 37 33 31 38 5d 0a 2a 2a 20 5b 48  ] [H17318].** [H
146b0 31 37 33 32 31 5d 20 5b 48 31 37 33 32 32 5d 20  17321] [H17322] 
146c0 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a 2a 2a 20 54  [H17323].**.** T
146d0 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
146e0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
146f0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
14700 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
14710 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
14720 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
14730 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
14740 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
14750 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
14760 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14770 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
14780 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
14790 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
147a0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
147b0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
147c0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
147d0 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
147e0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
147f0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
14800 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
14810 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
14820 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14830 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
14840 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
14850 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
14860 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
14870 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
14880 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
14890 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
148a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
148b0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
148c0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
148d0 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31   {H17370} <S3021
148e0 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0>.**.** SQLite 
148f0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
14900 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
14910 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
14920 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
14930 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
14940 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
14950 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
14960 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14970 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
14980 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
14990 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
149a0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
149b0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  em..**.** Requir
149c0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33  ements:.** [H173
149d0 37 31 5d 20 5b 48 31 37 33 37 33 5d 20 5b 48 31  71] [H17373] [H1
149e0 37 33 37 34 5d 20 5b 48 31 37 33 37 35 5d 0a 2a  7374] [H17375].*
149f0 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
14a00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
14a10 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
14a20 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
14a30 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
14a40 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
14a50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14a60 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
14a70 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
14a80 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30  r {H17390} <S200
14a90 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
14aa0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
14ab0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
14ac0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
14ad0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
14ae0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
14af0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
14b00 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
14b10 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
14b20 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
14b30 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
14b40 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
14b50 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
14b60 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
14b70 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
14b80 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
14b90 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
14ba0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
14bb0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
14bc0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
14bd0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
14be0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
14bf0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
14c00 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
14c10 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20   A call to this 
14c20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
14c30 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
14c40 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
14c50 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69   P..**.** The fi
14c60 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
14c70 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
14c80 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
14c90 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
14ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
14cb0 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
14cc0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
14cd0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
14ce0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
14cf0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
14d00 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
14d10 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
14d20 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75  * On all subsequ
14d30 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
14d40 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
14d50 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
14d60 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
14d70 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
14d80 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
14d90 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
14da0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
14db0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
14dc0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 39  ments:.** [H1739
14dd0 32 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  2].*/.void sqlit
14de0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
14df0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
14e00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14e10 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
14e20 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
14e30 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53  acks {H12500} <S
14e40 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  70100>.**.** Thi
14e50 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
14e60 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
14e70 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
14e80 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
14e90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14ea0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
14eb0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
14ec0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74  ment..** The aut
14ed0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14ee0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
14ef0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
14f00 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
14f10 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
14f20 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
14f30 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
14f40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
14f50 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
14f60 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
14f70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
14f80 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61  16_v2()].  At va
14f90 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
14fa0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
14fb0 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
14fc0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
14fd0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
14fe0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
14ff0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
15000 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15010 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
15020 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
15030 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
15040 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69  ed.  The authori
15050 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
15060 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
15070 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
15080 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
15090 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
150a0 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
150b0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
150c0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
150d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
150e0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
150f0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
15100 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
15110 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
15120 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
15130 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
15140 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
15150 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
15160 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
15170 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
15180 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
15190 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
151a0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
151b0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
151c0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
151d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
151e0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
151f0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
15200 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
15210 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
15220 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
15230 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
15240 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
15250 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
15260 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
15270 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
15280 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57  uested is ok.  W
15290 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
152a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
152b0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
152c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
152d0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
152e0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
152f0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
15300 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
15310 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
15320 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
15330 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
15340 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
15350 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
15360 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15370 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15380 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
15390 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
153a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
153b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
153c0 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
153d0 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  ce. The second p
153e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
153f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
15400 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
15410 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
15420 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
15430 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
15440 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
15450 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
15460 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
15470 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
15480 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
15490 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
154a0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
154b0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
154c0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
154d0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
154e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
154f0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  orized..**.** If
15500 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
15510 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
15520 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
15530 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
15540 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
15550 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
15560 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
15570 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
15580 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
15590 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
155a0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
155b0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
155c0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
155d0 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
155e0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
155f0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
15600 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
15610 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
15620 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
15630 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
15640 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
15650 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
15660 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
15670 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 61 63 74  e..** If the act
15680 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
15690 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
156a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
156b0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
156c0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
156d0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
156e0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
156f0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
15700 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
15710 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
15720 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
15730 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
15740 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
15750 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
15760 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
15770 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
15780 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
15790 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
157a0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
157b0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
157c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
157d0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
157e0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
157f0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
15800 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
15810 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
15820 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
15830 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
15840 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
15850 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
15860 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
15870 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
15880 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
15890 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
158a0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
158b0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
158c0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
158d0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
158e0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
158f0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
15900 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
15910 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
15920 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
15930 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
15940 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
15950 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
15960 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
15970 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
15980 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
15990 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
159a0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
159b0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
159c0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
159d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
159e0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
159f0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
15a00 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
15a10 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
15a20 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
15a30 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
15a40 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
15a50 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
15a60 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
15a70 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
15a80 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
15a90 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
15aa0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
15ab0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
15ac0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
15ad0 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20  r..**.** Only a 
15ae0 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
15af0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
15b00 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
15b10 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
15b20 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
15b30 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
15b40 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
15b50 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
15b60 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44  revious call.  D
15b70 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
15b80 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
15b90 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
15ba0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
15bb0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
15bc0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
15bd0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
15be0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
15bf0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
15c00 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
15c10 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
15c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
15c30 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
15c40 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15c50 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
15c60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15c70 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
15c80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
15c90 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
15ca0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
15cb0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
15cc0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
15cd0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
15ce0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  raph..**.** When
15cf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15d00 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
15d10 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
15d20 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
15d30 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
15d40 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
15d50 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
15d60 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
15d70 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
15d80 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
15d90 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
15da0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
15db0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
15dc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15dd0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
15de0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
15df0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
15e00 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
15e10 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
15e20 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15e30 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
15e40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15e50 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
15e60 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
15e70 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
15e80 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
15e90 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
15ea0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
15eb0 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
15ec0 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
15ed0 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
15ee0 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
15ef0 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
15f00 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
15f10 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
15f20 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
15f30 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
15f40 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  hange..**.** Req
15f50 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
15f60 31 32 35 30 31 5d 20 5b 48 31 32 35 30 32 5d 20  12501] [H12502] 
15f70 5b 48 31 32 35 30 33 5d 20 5b 48 31 32 35 30 34  [H12503] [H12504
15f80 5d 20 5b 48 31 32 35 30 35 5d 20 5b 48 31 32 35  ] [H12505] [H125
15f90 30 36 5d 20 5b 48 31 32 35 30 37 5d 20 5b 48 31  06] [H12507] [H1
15fa0 32 35 31 30 5d 0a 2a 2a 20 5b 48 31 32 35 31 31  2510].** [H12511
15fb0 5d 20 5b 48 31 32 35 31 32 5d 20 5b 48 31 32 35  ] [H12512] [H125
15fc0 32 30 5d 20 5b 48 31 32 35 32 31 5d 20 5b 48 31  20] [H12521] [H1
15fd0 32 35 32 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2522].*/.int sql
15fe0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
15ff0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
16000 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
16010 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
16020 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
16030 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
16040 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
16050 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
16060 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16070 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
16080 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39  urn Codes {H1259
16090 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a  0} <H12500>.**.*
160a0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
160b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
160c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
160d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
160e0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
160f0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
16100 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
16110 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
16120 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
16130 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
16140 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
16150 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
16160 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
16170 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
16180 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
16190 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
161a0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
161b0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
161c0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
161d0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
161e0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
161f0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
16200 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
16210 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
16220 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
16230 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
16240 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
16250 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
16260 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
16270 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
16280 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31  des {H12550} <H1
16290 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2500>.**.** The 
162a0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
162b0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
162c0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
162d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
162e0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
162f0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
16300 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
16310 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
16320 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
16330 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16340 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
16350 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
16360 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
16370 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
16380 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
16390 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
163a0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
163b0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
163c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
163d0 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
163e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
163f0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
16400 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
16410 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
16420 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
16430 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
16440 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
16450 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
16460 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
16470 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
16480 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
16490 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
164a0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
164b0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
164c0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
164d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
164e0 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
164f0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
16500 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16510 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
16520 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
16530 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
16540 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
16550 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20  cable.  The 6th 
16560 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16570 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16580 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
16590 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
165a0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
165b0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
165c0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
165d0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
165e0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
165f0 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
16600 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
16610 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
16620 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a   SQL code..**.**
16630 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
16640 2a 20 5b 48 31 32 35 35 31 5d 20 5b 48 31 32 35  * [H12551] [H125
16650 35 32 5d 20 5b 48 31 32 35 35 33 5d 20 5b 48 31  52] [H12553] [H1
16660 32 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  2554].*/./******
16670 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16680 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16690 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
166a0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
166b0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
166c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
166d0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
166e0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
166f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
16700 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16710 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
16720 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
16730 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
16740 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16750 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16760 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
16770 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
16780 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
16790 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
167a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
167b0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
167c0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
167d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
167e0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
167f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16800 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
16810 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
16820 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
16830 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
16840 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16850 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
16860 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
16870 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
16880 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
16890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
168a0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
168b0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
168c0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
168d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
168e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
168f0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
16900 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
16910 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
16920 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
16930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16940 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
16950 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
16960 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
16970 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
16980 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
16990 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
169a0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
169b0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
169c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
169d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
169e0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
169f0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
16a00 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
16a10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16a20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
16a30 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
16a40 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
16a50 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
16a60 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
16a70 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
16a80 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
16a90 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
16aa0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
16ab0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
16ac0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
16ad0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
16ae0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
16af0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
16b00 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
16b10 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
16b20 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
16b30 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
16b40 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
16b50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16b60 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
16b70 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
16b80 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
16b90 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
16ba0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16bb0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
16bc0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
16bd0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
16be0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
16bf0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16c00 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
16c10 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
16c20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
16c30 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16c40 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16c50 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
16c60 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
16c70 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
16c80 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
16c90 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
16ca0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
16cb0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
16cc0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
16cd0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
16ce0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16cf0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
16d00 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
16d10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
16d20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
16d30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16d40 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
16d50 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
16d60 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
16d70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
16d80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d90 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
16da0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
16db0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
16dc0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
16dd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16de0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
16df0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
16e00 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
16e10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
16e20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16e30 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
16e40 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
16e50 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
16e60 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
16e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
16e80 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
16e90 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
16ea0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
16eb0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
16ec0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
16ed0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
16ee0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
16ef0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
16f00 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16f10 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
16f20 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
16f30 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
16f40 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
16f50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
16f60 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
16f70 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
16f80 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
16f90 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
16fa0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
16fb0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
16fc0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
16fd0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
16fe0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
16ff0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
17000 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
17010 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
17020 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
17030 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
17040 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
17050 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
17060 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
17070 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
17080 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
17090 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
170a0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
170b0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
170c0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
170d0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
170e0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
170f0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
17100 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20  ctions {H12280} 
17110 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45  <S60400>.** EXPE
17120 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
17130 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
17140 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
17150 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
17160 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
17170 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
17180 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
17190 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
171a0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  tements..**.** T
171b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
171c0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
171d0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
171e0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
171f0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
17200 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
17210 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
17220 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
17230 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65  _step()]..** The
17240 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17250 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  s a UTF-8 render
17260 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ing of the SQL s
17270 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a  tatement text.**
17280 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
17290 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
172a0 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74  xecuting.  Addit
172b0 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  ional callbacks 
172c0 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
172d0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
172e0 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
172f0 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
17300 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
17310 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
17320 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
17330 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
17340 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
17350 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
17360 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
17370 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
17380 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
17390 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
173a0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
173b0 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65  es.  The profile
173c0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
173d0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
173e0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
173f0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
17400 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
17410 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
17420 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
17430 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a  nt took to run..
17440 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
17450 74 73 3a 0a 2a 2a 20 5b 48 31 32 32 38 31 5d 20  ts:.** [H12281] 
17460 5b 48 31 32 32 38 32 5d 20 5b 48 31 32 32 38 33  [H12282] [H12283
17470 5d 20 5b 48 31 32 32 38 34 5d 20 5b 48 31 32 32  ] [H12284] [H122
17480 38 35 5d 20 5b 48 31 32 32 38 37 5d 20 5b 48 31  85] [H12287] [H1
17490 32 32 38 38 5d 20 5b 48 31 32 32 38 39 5d 0a 2a  2288] [H12289].*
174a0 2a 20 5b 48 31 32 32 39 30 5d 0a 2a 2f 0a 53 51  * [H12290].*/.SQ
174b0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
174c0 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
174d0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
174e0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
174f0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
17500 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
17510 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
17520 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
17530 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
17540 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
17550 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
17560 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
17570 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
17580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
17590 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
175a0 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c  backs {H12910} <
175b0 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60400>.**.** Th
175c0 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69  is routine confi
175d0 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  gures a callback
175e0 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a   function - the.
175f0 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  ** progress call
17600 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69  back - that is i
17610 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
17620 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a  lly during long.
17630 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ** running calls
17640 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
17650 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
17660 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  tep()] and.** [s
17670 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
17680 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ()].  An example
17690 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
176a0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
176b0 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
176c0 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
176d0 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
176e0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
176f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17700 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
17710 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
17720 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
17730 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
17740 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
17750 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
17760 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
17770 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
17780 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
17790 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
177a0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
177b0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
177c0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
177d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
177e0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
177f0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
17800 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
17810 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
17820 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
17830 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
17840 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
17850 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
17860 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
17870 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
17880 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
17890 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  graph..**.** Req
178a0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
178b0 31 32 39 31 31 5d 20 5b 48 31 32 39 31 32 5d 20  12911] [H12912] 
178c0 5b 48 31 32 39 31 33 5d 20 5b 48 31 32 39 31 34  [H12913] [H12914
178d0 5d 20 5b 48 31 32 39 31 35 5d 20 5b 48 31 32 39  ] [H12915] [H129
178e0 31 36 5d 20 5b 48 31 32 39 31 37 5d 20 5b 48 31  16] [H12917] [H1
178f0 32 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  2918].**.*/.void
17900 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
17910 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
17920 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
17930 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
17940 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17950 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
17960 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
17970 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30  on {H12700} <S40
17980 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  200>.**.** These
17990 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
179a0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
179b0 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d  e file whose nam
179c0 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  e is given by th
179d0 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72  e.** filename ar
179e0 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65  gument. The file
179f0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
17a00 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
17a10 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
17a20 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
17a30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
17a40 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
17a50 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
17a60 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
17a70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
17a80 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  . A [database co
17a90 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
17aa0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
17ab0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
17ac0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
17ad0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
17ae0 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
17af0 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
17b00 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
17b10 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
17b20 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
17b30 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
17b40 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
17b50 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
17b60 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
17b70 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
17b80 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
17b90 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61  ect. If the data
17ba0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
17bb0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
17bc0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
17bd0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
17be0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
17bf0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
17c00 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
17c10 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b  urned.  The.** [
17c20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
17c30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
17c40 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
17c50 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
17c60 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
17c70 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
17c80 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
17c90 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  he error..**.** 
17ca0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
17cb0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
17cc0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
17cd0 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
17ce0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
17cf0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
17d00 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
17d10 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
17d20 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
17d30 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
17d40 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
17d50 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
17d60 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
17d70 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
17d80 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
17d90 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
17da0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
17db0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
17dc0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
17dd0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
17de0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
17df0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
17e00 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
17e10 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
17e20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
17e30 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
17e40 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
17e50 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
17e60 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
17e70 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
17e80 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
17e90 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
17ea0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
17eb0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
17ec0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66  nnection.  The f
17ed0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63  lags parameter c
17ee0 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
17ef0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
17f00 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
17f10 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
17f20 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
17f30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
17f40 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  TEX] or [SQLITE_
17f50 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
17f60 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c  flags:.**.** <dl
17f70 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45  >.** <dt>[SQLITE
17f80 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
17f90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
17fa0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
17fb0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
17fc0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
17fd0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
17fe0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
17ff0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
18000 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  turned.</dd>.**.
18010 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f  ** <dt>[SQLITE_O
18020 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
18030 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
18040 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
18050 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
18060 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
18070 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
18080 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
18090 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
180a0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
180b0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
180c0 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
180d0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
180e0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
180f0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
18100 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
18110 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  rned.</dd>.**.**
18120 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
18130 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
18140 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
18150 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
18160 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
18170 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
18180 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
18190 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69  and is creates i
181a0 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  t if.** it does 
181b0 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
181c0 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
181d0 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
181e0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
181f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
18200 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
18210 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20  en16().</dd>.** 
18220 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
18230 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
18240 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
18250 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
18260 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
18270 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
18280 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ove or one of th
18290 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  e combinations s
182a0 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69  hown above combi
182b0 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ned.** with the 
182c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
182d0 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45  UTEX] or [SQLITE
182e0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
182f0 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20   flags,.** then 
18300 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
18310 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
18320 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   If the [SQLITE_
18330 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
18340 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
18350 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
18360 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
18370 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
18380 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
18390 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
183a0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
183b0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
183c0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
183d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
183e0 74 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74  tart-time.  If t
183f0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
18400 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
18410 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
18420 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18430 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
18440 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
18450 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
18460 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
18470 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
18480 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
18490 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
184a0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
184b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
184c0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
184d0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
184e0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
184f0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
18500 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
18510 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
18520 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d  tion.  This in-m
18530 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
18540 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
18550 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
18560 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
18570 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
18580 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
18590 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
185a0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
185b0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
185c0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
185d0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
185e0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
185f0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
18600 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
18610 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
18620 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
18630 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
18640 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
18650 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
18660 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
18670 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
18680 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
18690 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66  iguity..**.** If
186a0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
186b0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
186c0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
186d0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
186e0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
186f0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
18700 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64    This private d
18710 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
18720 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
18730 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
18740 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
18750 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
18760 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
18770 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
18780 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
18790 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
187a0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
187b0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
187c0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
187d0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
187e0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
187f0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
18800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18810 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49  n should use.  I
18820 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
18830 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
18840 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
18850 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
18860 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
18870 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
18880 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
18890 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
188a0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
188b0 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
188c0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
188d0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
188e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
188f0 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
18900 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
18910 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
18920 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
18930 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
18940 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
18950 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
18960 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
18970 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
18980 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
18990 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
189a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
189b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
189c0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  2()..**.** Requi
189d0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
189e0 37 30 31 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48  701] [H12702] [H
189f0 31 32 37 30 33 5d 20 5b 48 31 32 37 30 34 5d 20  12703] [H12704] 
18a00 5b 48 31 32 37 30 36 5d 20 5b 48 31 32 37 30 37  [H12706] [H12707
18a10 5d 20 5b 48 31 32 37 30 39 5d 20 5b 48 31 32 37  ] [H12709] [H127
18a20 31 31 5d 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20  11].** [H12712] 
18a30 5b 48 31 32 37 31 33 5d 20 5b 48 31 32 37 31 34  [H12713] [H12714
18a40 5d 20 5b 48 31 32 37 31 37 5d 20 5b 48 31 32 37  ] [H12717] [H127
18a50 31 39 5d 20 5b 48 31 32 37 32 31 5d 20 5b 48 31  19] [H12721] [H1
18a60 32 37 32 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  2723].*/.int sql
18a70 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
18a80 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
18a90 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
18aa0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
18ab0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
18ac0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
18ad0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
18ae0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
18af0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
18b00 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
18b10 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
18b20 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
18b30 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
18b40 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
18b50 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
18b60 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
18b70 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
18b80 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
18b90 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
18ba0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
18bb0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
18bc0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
18bd0 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
18be0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
18bf0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
18c00 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
18c10 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
18c20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
18c30 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
18c40 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
18c50 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
18c60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
18c70 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
18c80 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d  essages {H12800}
18c90 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60200>.**.** 
18ca0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
18cb0 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
18cc0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
18cd0 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
18ce0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
18cf0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
18d00 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
18d10 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
18d20 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
18d30 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
18d40 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
18d50 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
18d60 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
18d70 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
18d80 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
18d90 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
18da0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
18db0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
18dc0 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
18dd0 65 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c  efined.  The sql
18de0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
18df0 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
18e00 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
18e10 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
18e20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
18e30 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
18e40 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
18e50 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
18e60 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
18e70 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
18e80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
18e90 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
18ea0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
18eb0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
18ec0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
18ed0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
18ee0 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
18ef0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
18f00 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
18f10 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20  y..** Memory to 
18f20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
18f30 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
18f40 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
18f50 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
18f60 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
18f70 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
18f80 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
18f90 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
18fa0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
18fb0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
18fc0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
18fd0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
18fe0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
18ff0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
19000 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
19010 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ions..**.** When
19020 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
19030 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
19040 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
19050 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
19060 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
19070 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
19080 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
19090 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
190a0 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
190b0 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
190c0 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
190d0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
190e0 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
190f0 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
19100 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
19110 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
19120 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
19130 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
19140 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
19150 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
19160 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
19170 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
19180 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
19190 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
191a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
191b0 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
191c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
191d0 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
191e0 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
191f0 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
19200 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
19210 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
19220 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
19230 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
19240 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
19250 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
19260 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
19270 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
19280 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
19290 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
192a0 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
192b0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
192c0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
192d0 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
192e0 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
192f0 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
19300 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
19310 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
19320 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
19330 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a  y not be set..**
19340 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
19350 3a 0a 2a 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48  :.** [H12801] [H
19360 31 32 38 30 32 5d 20 5b 48 31 32 38 30 33 5d 20  12802] [H12803] 
19370 5b 48 31 32 38 30 37 5d 20 5b 48 31 32 38 30 38  [H12807] [H12808
19380 5d 20 5b 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e  ] [H12809].*/.in
19390 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
193a0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
193b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
193c0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
193d0 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
193e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
193f0 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
19400 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
19410 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
19420 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19430 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
19440 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
19450 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e  H13000} <H13010>
19460 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
19470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19480 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
19490 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
194a0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
194b0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
194c0 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
194d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
194e0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
194f0 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
19500 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
19510 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
19520 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
19530 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
19540 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
19550 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
19560 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
19570 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
19580 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
19590 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
195a0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
195b0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
195c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
195d0 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
195e0 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
195f0 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
19600 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
19610 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
19620 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
19630 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
19640 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
19650 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
19660 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
19670 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
19680 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
19690 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
196a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
196b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
196c0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
196d0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
196e0 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
196f0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
19700 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
19710 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
19720 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
19730 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
19740 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
19750 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
19760 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
19770 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
19780 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
19790 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
197a0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
197b0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
197c0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
197d0 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
197e0 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d   Limits {H12760}
197f0 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20600>.**.** 
19800 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
19810 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
19820 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
19830 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
19840 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
19850 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
19860 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
19870 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
19880 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
19890 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
198a0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
198b0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
198c0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
198d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
198e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
198f0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
19900 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
19910 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
19920 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
19930 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
19940 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
19950 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
19960 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
19970 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  uct.  The functi
19980 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f  on returns the o
19990 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  ld limit..**.** 
199a0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
199b0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
199c0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
199d0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
199e0 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  * For the limit 
199f0 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
19a00 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
19a10 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
19a20 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
19a30 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62   bound].** set b
19a40 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  y a compile-time
19a50 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
19a60 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20  macro named .** 
19a70 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
19a80 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54  _MAX_XYZ]..** (T
19a90 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
19aa0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
19ab0 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
19ac0 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20  .** Attempts to 
19ad0 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
19ae0 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
19af0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
19b00 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
19b10 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
19b20 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a  d upper limit..*
19b30 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69  *.** Run time li
19b40 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
19b50 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
19b60 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
19b70 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
19b80 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
19b90 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
19ba0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
19bb0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
19bc0 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
19bd0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
19be0 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
19bf0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
19c00 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
19c10 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
19c20 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
19c30 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
19c40 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
19c50 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
19c60 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
19c70 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
19c80 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
19c90 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
19ca0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
19cb0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
19cc0 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
19cd0 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
19ce0 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
19cf0 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
19d00 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
19d10 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
19d20 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
19d30 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
19d40 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
19d50 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
19d60 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
19d70 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
19d80 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
19d90 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
19da0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
19db0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
19dc0 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
19dd0 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
19de0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
19df0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
19e00 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
19e10 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
19e20 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
19e30 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
19e40 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
19e50 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
19e60 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
19e70 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
19e80 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
19e90 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
19ea0 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20  ts:.** [H12762] 
19eb0 5b 48 31 32 37 36 36 5d 20 5b 48 31 32 37 36 39  [H12766] [H12769
19ec0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
19ed0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
19ee0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
19ef0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
19f00 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
19f10 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
19f20 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36   {H12790} <H1276
19f30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
19f40 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
19f50 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   {limit categori
19f60 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
19f70 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
19f80 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
19f90 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
19fa0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
19fb0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
19fc0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
19fd0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
19fe0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
19ff0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1a000 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
1a010 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
1a020 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
1a030 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
1a040 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
1a050 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
1a060 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
1a070 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1a080 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
1a090 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1a0a0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
1a0b0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
1a0c0 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a   table row.<dd>.
1a0d0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a0e0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
1a0f0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1a100 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1a110 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
1a120 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
1a130 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1a140 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
1a150 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1a160 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1a170 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
1a180 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
1a190 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
1a1a0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
1a1b0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
1a1c0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1a1d0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
1a1e0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
1a1f0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
1a200 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  use.</dd>.**.** 
1a210 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1a220 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
1a230 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1a240 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
1a250 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
1a260 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
1a270 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1a280 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1a290 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
1a2a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1a2b0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
1a2c0 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
1a2d0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1a2e0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1a2f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1a300 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1a310 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1a320 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1a330 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1a340 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1a350 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1a360 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1a370 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1a380 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a390 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1a3a0 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
1a3b0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1a3c0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
1a3d0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
1a3e0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1a3f0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1a400 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
1a410 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1a420 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
1a430 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1a440 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  s].</dd>.**.** <
1a450 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1a460 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
1a470 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1a480 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1a490 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
1a4a0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
1a4b0 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
1a4c0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
1a4d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1a4e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1a4f0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
1a500 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1a510 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76  imum number of v
1a520 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53  ariables in an S
1a530 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
1a540 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e  t can.** be boun
1a550 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  d.</dd>.** </dl>
1a560 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1a570 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1a580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a590 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1a5a0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1a5b0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1a5c0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1a5d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1a5e0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1a5f0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1a600 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1a610 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1a620 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1a630 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1a640 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1a650 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1a660 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1a670 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1a680 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1a690 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1a6a0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1a6b0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1a6c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1a6d0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1a6e0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1a6f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1a700 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1a710 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1a720 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1a730 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1a740 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f  R           9../
1a750 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1a760 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
1a770 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31  Statement {H1301
1a780 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b  0} <S10000>.** K
1a790 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
1a7a0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1a7b0 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
1a7c0 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
1a7d0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
1a7e0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
1a7f0 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
1a800 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
1a810 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1a820 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1a830 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
1a840 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
1a850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
1a860 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
1a870 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
1a880 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1a890 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1a8a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1a8b0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1a8c0 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
1a8d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a8e0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
1a8f0 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
1a900 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1a910 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
1a920 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
1a930 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
1a940 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
1a950 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1a960 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
1a970 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1a980 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1a990 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
1a9a0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
1a9b0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
1a9c0 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
1a9d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1a9e0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
1a9f0 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  16..**.** If the
1aa00 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1aa10 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1aa20 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
1aa30 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
1aa40 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
1aa50 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74  minator. If nByt
1aa60 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1aa70 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
1aa80 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
1aa90 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
1aaa0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57  ad from zSql.  W
1aab0 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
1aac0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
1aad0 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
1aae0 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
1aaf0 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
1ab00 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
1ab10 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
1ab20 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
1ab30 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
1ab40 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
1ab50 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
1ab60 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
1ab70 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
1ab80 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
1ab90 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
1aba0 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
1abb0 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
1abc0 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
1abd0 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
1abe0 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
1abf0 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
1ac00 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
1ac10 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
1ac20 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
1ac30 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
1ac40 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a  tor bytes..**.**
1ac50 20 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f   If pzTail is no
1ac60 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
1ac70 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
1ac80 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
1ac90 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
1aca0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
1acb0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
1acc0 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
1acd0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
1ace0 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
1acf0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
1ad00 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
1ad10 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
1ad20 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
1ad30 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
1ad40 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
1ad50 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
1ad60 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
1ad70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ad80 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
1ad90 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
1ada0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1adb0 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69  ()].  If there i
1adc0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
1add0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
1ade0 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69   NULL.  If the i
1adf0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
1ae00 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
1ae10 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
1ae20 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
1ae30 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
1ae40 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
1ae50 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
1ae60 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
1ae70 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
1ae80 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
1ae90 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
1aea0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
1aeb0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1aec0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
1aed0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1aee0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
1aef0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
1af00 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
1af10 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  s, [SQLITE_OK] i
1af20 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65  s returned, othe
1af30 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1af40 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1af50 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1af60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1af70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1af80 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
1af90 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
1afa0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
1afb0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
1afc0 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
1afd0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
1afe0 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
1aff0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1b000 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
1b010 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
1b020 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22  ged..** In the "
1b030 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1b040 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1b050 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1b060 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1b070 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1b080 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1b090 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
1b0a0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1b0b0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
1b0c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1b0d0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1b0e0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69  o.** behave a di
1b0f0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f  fferently in two
1b100 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1b110 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20  >.** <li>.** If 
1b120 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1b130 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
1b140 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
1b150 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
1b160 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
1b170 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
1b180 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1b190 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
1b1a0 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
1b1b0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1b1c0 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
1b1d0 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68  it again.  If th
1b1e0 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
1b1f0 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
1b200 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
1b210 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
1b220 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
1b230 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1b240 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
1b250 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1b260 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
1b270 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1b280 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  r, [SQLITE_SCHEM
1b290 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66  A] is.** now a f
1b2a0 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c  atal error.  Cal
1b2b0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
1b2c0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69  epare_v2()] agai
1b2d0 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20  n will not make 
1b2e0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20  the.** error go 
1b2f0 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65  away.  Note: use
1b300 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1b310 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ()] to find the 
1b320 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70  text.** of the p
1b330 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61  arsing error tha
1b340 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20  t results in an 
1b350 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1b360 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e  return..** </li>
1b370 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57  .**.** <li>.** W
1b380 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
1b390 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
1b3a0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
1b3b0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
1b3c0 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
1b3d0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
1b3e0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
1b3f0 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65  .  The legacy be
1b400 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
1b410 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1b420 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
1b430 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
1b440 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
1b450 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
1b460 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65  d you would have
1b470 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1b480 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1b490 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f  e3_reset()] in o
1b4a0 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20  rder.** to find 
1b4b0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1b4c0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1b4d0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1b4e0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1b4f0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1b500 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1b510 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1b520 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1b530 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1b540 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
1b550 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1b560 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31 32  [H13011] [H13012
1b570 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33 30  ] [H13013] [H130
1b580 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48 31  14] [H13015] [H1
1b590 33 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20 5b  3016] [H13019] [
1b5a0 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e  H13021].**.*/.in
1b5b0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1b5c0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1b5d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1b5e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1b5f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1b600 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1b610 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1b620 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1b630 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1b640 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1b650 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1b660 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1b670 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1b680 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1b690 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1b6a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1b6b0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1b6c0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1b6d0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1b6e0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1b6f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1b700 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
1b710 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1b720 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1b730 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1b740 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1b750 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1b760 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1b770 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1b780 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1b790 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1b7a0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1b7b0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1b7c0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1b7d0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1b7e0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1b7f0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1b800 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1b810 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1b820 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1b830 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1b840 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
1b850 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1b860 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1b870 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1b880 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1b890 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1b8a0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1b8b0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1b8c0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1b8d0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1b8e0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1b8f0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1b900 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1b910 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1b920 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1b930 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1b940 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1b950 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1b960 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1b970 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1b980 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1b990 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
1b9a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1b9b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1b9c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1b9d0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1b9e0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1b9f0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1ba00 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1ba10 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1ba20 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1ba30 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1ba40 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1ba50 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1ba60 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1ba70 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1ba80 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1ba90 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1baa0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1bab0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1bac0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1bad0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
1bae0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20  g Statement SQL 
1baf0 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30  {H13100} <H13000
1bb00 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
1bb10 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
1bb20 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
1bb30 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
1bb40 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
1bb50 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
1bb60 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
1bb70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
1bb80 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1bb90 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
1bba0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1bbb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1bbc0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1bbd0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1bbe0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1bbf0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31 5d  nts:.** [H13101]
1bc00 20 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31 30   [H13102] [H1310
1bc10 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  3].*/.const char
1bc20 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
1bc30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1bc40 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1bc50 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
1bc60 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
1bc70 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32  ect {H15000} <S2
1bc80 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
1bc90 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
1bca0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
1bcb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1bcc0 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
1bcd0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
1bce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1bcf0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
1bd00 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
1bd10 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
1bd20 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
1bd30 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
1bd40 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
1bd50 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
1bd60 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56  ues it stores. V
1bd70 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
1bd80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1bd90 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
1bda0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
1bdb0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
1bdc0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
1bdd0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
1bde0 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
1bdf0 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
1be00 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
1be10 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
1be20 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
1be30 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
1be40 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1be50 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
1be60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
1be70 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
1be80 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
1be90 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
1bea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1beb0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
1bec0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
1bed0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
1bee0 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
1bef0 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
1bf00 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
1bf10 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1bf20 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
1bf30 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
1bf40 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
1bf50 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
1bf60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
1bf70 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
1bf80 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20  ld.  A internal 
1bf90 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1bfa0 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
1bfb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1bfc0 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
1bfd0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1bfe0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
1bff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1c000 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
1c010 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
1c020 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
1c030 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
1c040 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1c050 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
1c060 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1c070 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
1c080 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
1c090 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
1c0a0 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
1c0b0 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
1c0c0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
1c0d0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
1c0e0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1c0f0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
1c100 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1c110 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
1c120 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1c130 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1c140 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1c150 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
1c160 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
1c170 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
1c180 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
1c190 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
1c1a0 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
1c1b0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
1c1c0 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
1c1d0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
1c1e0 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65  n between betwee
1c1f0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1c200 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1c210 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1c220 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
1c230 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
1c240 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
1c250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1c260 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
1c270 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
1c280 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
1c290 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1c2a0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
1c2b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1c2c0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
1c2d0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ted..** The sqli
1c2e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1c2f0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1c300 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1c310 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
1c320 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
1c330 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1c340 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
1c350 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
1c360 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
1c370 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
1c380 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
1c390 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
1c3a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
1c3b0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
1c3c0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
1c3d0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
1c3e0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
1c3f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1c400 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
1c410 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1c420 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
1c430 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
1c440 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
1c450 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
1c460 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32  t {H16001} <S202
1c470 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  00>.**.** The co
1c480 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
1c490 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
1c4a0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
1c4b0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
1c4c0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1c4d0 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  t.  A pointer to
1c4e0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
1c4f0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
1c500 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
1c510 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
1c520 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1c530 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
1c540 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1c550 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1c560 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
1c570 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
1c580 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
1c590 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
1c5a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c5b0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
1c5c0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
1c5d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
1c5e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
1c5f0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
1c600 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
1c610 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
1c620 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
1c630 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
1c640 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
1c650 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
1c660 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
1c670 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1c680 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
1c690 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
1c6a0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
1c6b0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
1c6c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
1c6d0 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30   {H13500} <S7030
1c6e0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1c6f0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
1c700 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1c710 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
1c720 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
1c730 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
1c740 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
1c750 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
1c760 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
1c770 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69   In the SQL stri
1c780 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ngs input to [sq
1c790 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c7a0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
1c7b0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
1c7c0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
1c7d0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
1c7e0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
1c7f0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
1c800 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
1c810 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
1c820 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
1c830 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
1c840 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
1c850 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
1c860 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
1c870 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
1c880 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
1c890 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
1c8a0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
1c8b0 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
1c8c0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
1c8d0 6e 74 69 66 65 72 2e 20 20 54 68 65 20 76 61 6c  ntifer.  The val
1c8e0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
1c8f0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1c900 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1c910 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
1c920 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
1c930 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
1c940 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
1c950 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1c960 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
1c970 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
1c980 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1c990 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1c9a0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
1c9b0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
1c9c0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1c9d0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1c9e0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
1c9f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1ca00 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1ca10 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
1ca20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1ca30 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1ca40 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
1ca50 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
1ca60 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73  ..** The leftmos
1ca70 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
1ca80 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
1ca90 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d  1.  When the sam
1caa0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
1cab0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
1cac0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
1cad0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
1cae0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
1caf0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
1cb00 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
1cb10 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1cb20 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20  e..** The index 
1cb30 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
1cb40 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
1cb50 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
1cb60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1cb70 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1cb80 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
1cb90 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a  ed.  The index.*
1cba0 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
1cbb0 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
1cbc0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
1cbd0 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
1cbe0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
1cbf0 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
1cc00 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
1cc10 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
1cc20 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1cc30 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
1cc40 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1cc50 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
1cc60 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
1cc70 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
1cc80 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1cc90 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  * In those routi
1cca0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1ccb0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1ccc0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1ccd0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
1cce0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
1ccf0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1cd00 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1cd10 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1cd20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
1cd30 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1cd40 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1cd50 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49  characters..** I
1cd60 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1cd70 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
1cd80 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
1cd90 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
1cda0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1cdb0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
1cdc0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1cdd0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  inator..**.** Th
1cde0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1cdf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
1ce00 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
1ce10 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
1ce20 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
1ce30 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
1ce40 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
1ce50 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
1ce60 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
1ce70 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
1ce80 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1ce90 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69  th it. If the fi
1cea0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1ceb0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1cec0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1ced0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1cee0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1cef0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1cf00 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1cf10 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1cf20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1cf30 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1cf40 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61  * If the fifth a
1cf50 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
1cf60 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
1cf70 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
1cf80 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
1cf90 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
1cfa0 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
1cfb0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
1cfc0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
1cfd0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1cfe0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
1cff0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1d000 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
1d010 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
1d020 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
1d030 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
1d040 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
1d050 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
1d060 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
1d070 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
1d080 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
1d090 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
1d0a0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
1d0b0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
1d0c0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
1d0d0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
1d0e0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
1d0f0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
1d100 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
1d110 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
1d120 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1d130 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
1d140 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
1d150 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65  outines..** A ne
1d160 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
1d170 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
1d180 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
1d190 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
1d1a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1d1b0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1d1c0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
1d1d0 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  after.** [sqlite
1d1e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d1f0 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74  (and its variant
1d200 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  s) or [sqlite3_r
1d210 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62  eset()] and.** b
1d220 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
1d230 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69  tep()]..** Bindi
1d240 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
1d250 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
1d260 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
1d270 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64  tine..** Unbound
1d280 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1d290 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
1d2a0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ULL..**.** These
1d2b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1d2c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
1d2d0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72  success or an er
1d2e0 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61  ror code if.** a
1d2f0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
1d300 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e  ng.  [SQLITE_RAN
1d310 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
1d320 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1d330 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
1d340 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c   of range.  [SQL
1d350 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
1d360 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
1d370 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51  () fails..** [SQ
1d380 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67  LITE_MISUSE] mig
1d390 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
1d3a0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1d3b0 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61   are called on a
1d3c0 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68  .** virtual mach
1d3d0 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20  ine that is the 
1d3e0 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77  wrong state or w
1d3f0 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79  hich has already
1d400 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
1d410 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66  .** Detection of
1d420 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c   misuse is unrel
1d430 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74  iable.  Applicat
1d440 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
1d450 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c  depend.** on SQL
1d460 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72  ITE_MISUSE retur
1d470 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55  ns.  SQLITE_MISU
1d480 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  SE is intended t
1d490 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20  o indicate a.** 
1d4a0 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  a logic error in
1d4b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1d4c0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1d4d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1d4e0 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68  ht.** panic rath
1d4f0 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53  er than return S
1d500 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
1d510 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1d520 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1d530 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
1d540 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1d550 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1d560 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1d570 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1d580 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
1d590 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1d5a0 20 5b 48 31 33 35 30 36 5d 20 5b 48 31 33 35 30   [H13506] [H1350
1d5b0 39 5d 20 5b 48 31 33 35 31 32 5d 20 5b 48 31 33  9] [H13512] [H13
1d5c0 35 31 35 5d 20 5b 48 31 33 35 31 38 5d 20 5b 48  515] [H13518] [H
1d5d0 31 33 35 32 31 5d 20 5b 48 31 33 35 32 34 5d 20  13521] [H13524] 
1d5e0 5b 48 31 33 35 32 37 5d 0a 2a 2a 20 5b 48 31 33  [H13527].** [H13
1d5f0 35 33 30 5d 20 5b 48 31 33 35 33 33 5d 20 5b 48  530] [H13533] [H
1d600 31 33 35 33 36 5d 20 5b 48 31 33 35 33 39 5d 20  13536] [H13539] 
1d610 5b 48 31 33 35 34 32 5d 20 5b 48 31 33 35 34 35  [H13542] [H13545
1d620 5d 20 5b 48 31 33 35 34 38 5d 20 5b 48 31 33 35  ] [H13548] [H135
1d630 35 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71  51].**.*/.int sq
1d640 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1d650 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1d660 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
1d670 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1d680 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1d690 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
1d6a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1d6b0 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
1d6c0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
1d6d0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
1d6e0 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
1d6f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
1d700 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
1d710 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
1d720 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
1d730 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
1d740 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d750 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1d760 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
1d770 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1d780 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
1d790 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1d7a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1d7b0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
1d7c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1d7d0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
1d7e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1d7f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1d800 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
1d810 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1d820 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
1d830 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1d840 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
1d850 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1d860 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
1d870 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
1d880 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
1d890 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30  rs {H13600} <S70
1d8a0 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  300>.**.** This 
1d8b0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
1d8c0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
1d8d0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
1d8e0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
1d8f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1d900 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
1d910 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
1d920 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
1d930 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
1d940 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
1d950 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
1d960 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
1d970 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
1d980 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
1d990 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1d9a0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
1d9b0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
1d9c0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
1d9d0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1d9e0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
1d9f0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1da00 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
1da10 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
1da20 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
1da30 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
1da40 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
1da50 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
1da60 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
1da70 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
1da80 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
1da90 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c  e ?NNN are used,
1daa0 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
1dab0 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
1dac0 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  t..**.** See als
1dad0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1dae0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1daf0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1db00 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1db10 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
1db20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1db30 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1db40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
1db50 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36  ements:.** [H136
1db60 30 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  01].*/.int sqlit
1db70 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1db80 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
1db90 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
1dba0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
1dbb0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
1dbc0 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33  r {H13620} <S703
1dbd0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
1dbe0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1dbf0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1dc00 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68  name of the n-th
1dc10 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  .** [SQL paramet
1dc20 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72  er] in a [prepar
1dc30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1dc40 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  * SQL parameters
1dc50 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
1dc60 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1dc70 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1dc80 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
1dc90 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
1dca0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
1dcb0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1dcc0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
1dcd0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
1dce0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
1dcf0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
1dd00 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
1dd10 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
1dd20 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
1dd30 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65   name..** Parame
1dd40 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
1dd50 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
1dd60 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
1dd70 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
1dd80 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65   and are also re
1dd90 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e  ferred to as "an
1dda0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
1ddb0 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  rs"..**.** The f
1ddc0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
1ddd0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1dde0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
1ddf0 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65  .** If the value
1de00 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   n is out of ran
1de10 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74  ge or if the n-t
1de20 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1de30 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
1de40 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
1de50 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  d.  The returned
1de60 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
1de70 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
1de80 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
1de90 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
1dea0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
1deb0 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
1dec0 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
1ded0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1dee0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1def0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1df00 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1df10 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1df20 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1df30 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1df40 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1df50 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
1df60 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1df70 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1df80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
1df90 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36  ements:.** [H136
1dfa0 32 31 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  21].*/.const cha
1dfb0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
1dfc0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
1dfd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1dfe0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1dff0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
1e000 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
1e010 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33   Given Name {H13
1e020 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  640} <S70300>.**
1e030 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69  .** Return the i
1e040 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
1e050 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
1e060 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a  ts name.  The.**
1e070 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
1e080 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
1e090 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
1e0a0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
1e0b0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1e0c0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1e0d0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a  e3_bind()].  A z
1e0e0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
1e0f0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
1e100 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
1e110 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d  ound.  The param
1e120 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
1e130 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
1e140 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
1e150 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1e160 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
1e170 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
1e180 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
1e190 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1e1a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
1e1b0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1e1c0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1e1d0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1e1e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1e1f0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
1e200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1e210 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1e220 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  x()]..**.** Requ
1e230 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1e240 33 36 34 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  3641].*/.int sql
1e250 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1e260 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
1e270 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
1e280 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
1e290 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1e2a0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
1e2b0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
1e2c0 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30  tatement {H13660
1e2d0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
1e2e0 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65   Contrary to the
1e2f0 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
1e300 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
1e310 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
1e320 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
1e330 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1e340 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
1e350 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e360 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69  ent]..** Use thi
1e370 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
1e380 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
1e390 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
1e3a0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1e3b0 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 36 31 5d 0a  ts:.** [H13661].
1e3c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1e3d0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
1e3e0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
1e3f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1e400 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
1e410 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
1e420 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30   {H13710} <S1070
1e430 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0>.**.** Return 
1e440 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1e450 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
1e460 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
1e470 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
1e480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1e490 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1e4a0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
1e4b0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
1e4c0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
1e4d0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
1e4e0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
1e4f0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
1e500 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1e510 0a 2a 2a 20 5b 48 31 33 37 31 31 5d 0a 2a 2f 0a  .** [H13711].*/.
1e520 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
1e530 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
1e540 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1e550 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e560 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
1e570 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31  A Result Set {H1
1e580 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3720} <S10700>.*
1e590 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1e5a0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
1e5b0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
1e5c0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
1e5d0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
1e5e0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
1e5f0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1e600 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
1e610 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
1e620 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1e630 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1e640 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1e650 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
1e660 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
1e670 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
1e680 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1e690 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
1e6a0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
1e6b0 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74  ring.  The first
1e6c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1e6d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1e6e0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
1e6f0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
1e700 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1e710 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
1e720 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1e730 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
1e740 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   The leftmost co
1e750 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
1e760 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75  ..**.** The retu
1e770 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
1e780 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
1e790 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
1e7a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e7b0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
1e7c0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1e7d0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
1e7e0 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
1e7f0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
1e800 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
1e810 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1e820 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
1e830 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
1e840 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
1e850 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
1e860 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
1e870 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
1e880 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
1e890 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
1e8a0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
1e8b0 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
1e8c0 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
1e8d0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
1e8e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  d..**.** The nam
1e8f0 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
1e900 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
1e910 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
1e920 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
1e930 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
1e940 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
1e950 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
1e960 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
1e970 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
1e980 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
1e990 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
1e9a0 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
1e9b0 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
1e9c0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
1e9d0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ext..**.** Requi
1e9e0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1e9f0 37 32 31 5d 20 5b 48 31 33 37 32 33 5d 20 5b 48  721] [H13723] [H
1ea00 31 33 37 32 34 5d 20 5b 48 31 33 37 32 35 5d 20  13724] [H13725] 
1ea10 5b 48 31 33 37 32 36 5d 20 5b 48 31 33 37 32 37  [H13726] [H13727
1ea20 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ].*/.const char 
1ea30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1ea40 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1ea50 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
1ea60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1ea70 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
1ea80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1ea90 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
1eaa0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
1eab0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
1eac0 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20  Result {H13740} 
1ead0 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
1eae0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
1eaf0 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
1eb00 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20   determine what 
1eb10 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a  column of what.*
1eb20 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68  * table in which
1eb30 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75   database a resu
1eb40 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  lt of a [SELECT]
1eb50 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73   statement comes
1eb60 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61   from..** The na
1eb70 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1eb80 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
1eb90 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
1eba0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
1ebb0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
1ebc0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
1ebd0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
1ebe0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
1ebf0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
1ec00 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
1ec10 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
1ec20 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
1ec30 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
1ec40 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
1ec50 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
1ec60 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  e..** The return
1ec70 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
1ec80 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
1ec90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1eca0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
1ecb0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
1ecc0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
1ecd0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
1ece0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
1ecf0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
1ed00 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
1ed10 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
1ed20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
1ed30 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
1ed40 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
1ed50 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
1ed60 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
1ed70 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
1ed80 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1ed90 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
1eda0 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
1edb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1edc0 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20  ment]..** These 
1edd0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
1ede0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
1edf0 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  ut the Nth colum
1ee00 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
1ee10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
1ee20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1ee30 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
1ee40 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49  rgument..**.** I
1ee50 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
1ee60 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1ee70 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
1ee80 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
1ee90 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
1eea0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
1eeb0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
1eec0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
1eed0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
1eee0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
1eef0 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
1ef00 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
1ef10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1ef20 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
1ef30 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79   Otherwise, they
1ef40 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
1ef50 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
1ef60 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
1ef70 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74  .** and column t
1ef80 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
1ef90 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
1efa0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
1efb0 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74  * As with all ot
1efc0 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
1efd0 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64   those postfixed
1efe0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
1eff0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
1f000 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65  ded strings, the
1f010 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
1f020 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b   return UTF-8. {
1f030 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
1f040 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
1f050 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
1f060 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
1f070 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
1f080 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
1f090 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
1f0a0 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
1f0b0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
1f0c0 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a  **.** {A13751}.*
1f0d0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
1f0e0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
1f0f0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
1f100 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
1f110 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
1f120 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f130 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
1f140 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
1f150 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
1f160 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
1f170 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1f180 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 34 31  ents:.** [H13741
1f190 5d 20 5b 48 31 33 37 34 32 5d 20 5b 48 31 33 37  ] [H13742] [H137
1f1a0 34 33 5d 20 5b 48 31 33 37 34 34 5d 20 5b 48 31  43] [H13744] [H1
1f1b0 33 37 34 35 5d 20 5b 48 31 33 37 34 36 5d 20 5b  3745] [H13746] [
1f1c0 48 31 33 37 34 38 5d 0a 2a 2a 0a 2a 2a 20 49 66  H13748].**.** If
1f1d0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
1f1e0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
1f1f0 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
1f200 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
1f210 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
1f220 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
1f230 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
1f240 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
1f250 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
1f260 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
1f270 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
1f280 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
1f290 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
1f2a0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1f2b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1f2c0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
1f2d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1f2e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1f2f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
1f300 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
1f310 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
1f320 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1f330 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
1f340 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1f350 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1f360 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1f370 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
1f380 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1f390 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
1f3a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
1f3b0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
1f3c0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1f3d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1f3e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
1f3f0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
1f400 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
1f410 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1f420 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
1f430 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
1f440 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37  t {H13760} <S107
1f450 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  00>.**.** The fi
1f460 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1f470 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1f480 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
1f490 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
1f4a0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
1f4b0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
1f4c0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
1f4d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
1f4e0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
1f4f0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
1f500 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
1f510 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
1f520 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
1f530 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
1f540 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
1f550 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
1f560 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20  turned.  If the 
1f570 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
1f580 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
1f590 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
1f5a0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
1f5b0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
1f5c0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1f5d0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
1f5e0 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
1f5f0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b  UTF-8 encoded. {
1f600 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  END}.**.** For e
1f610 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
1f620 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1f630 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
1f640 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
1f650 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
1f660 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
1f670 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
1f680 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
1f690 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
1f6a0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
1f6b0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
1f6c0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
1f6d0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
1f6e0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
1f6f0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
1f700 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
1f710 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
1f720 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
1f730 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a  lumn (i==0)..**.
1f740 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  ** SQLite uses d
1f750 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
1f760 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74  typing.  So just
1f770 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
1f780 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
1f790 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
1f7a0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
1f7b0 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
1f7c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
1f7d0 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
1f7e0 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
1f7f0 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
1f800 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
1f810 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
1f820 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
1f830 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
1f840 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f   Type.** is asso
1f850 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
1f860 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
1f870 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
1f880 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
1f890 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
1f8a0 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ues..**.** Requi
1f8b0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1f8c0 37 36 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b 48  761] [H13762] [H
1f8d0 31 33 37 36 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20  13763].*/.const 
1f8e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1f8f0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
1f900 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
1f910 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1f920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
1f930 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
1f940 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
1f950 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
1f960 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
1f970 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20  tement {H13200} 
1f980 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S10000>.**.** A
1f990 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
1f9a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
1f9b0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
1f9c0 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
1f9d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f9e0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
1f9f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1fa00 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
1fa10 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
1fa20 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
1fa30 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
1fa40 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1fa50 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
1fa60 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
1fa70 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
1fa80 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
1fa90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
1faa0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
1fab0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
1fac0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1fad0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
1fae0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
1faf0 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
1fb00 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
1fb10 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
1fb20 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
1fb30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1fb40 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1fb50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1fb60 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
1fb70 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
1fb80 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
1fb90 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
1fba0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fbb0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
1fbc0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
1fbd0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
1fbe0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1fbf0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
1fc00 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
1fc10 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
1fc20 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
1fc30 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
1fc40 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  * In the legacy 
1fc50 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
1fc60 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
1fc70 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
1fc80 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
1fc90 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
1fca0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
1fcb0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
1fcc0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
1fcd0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69   With the "v2" i
1fce0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
1fcf0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
1fd00 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
1fd10 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1fd20 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
1fd30 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
1fd40 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
1fd50 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
1fd60 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
1fd70 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
1fd80 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
1fd90 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
1fda0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
1fdb0 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
1fdc0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
1fdd0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
1fde0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
1fdf0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
1fe00 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
1fe10 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
1fe20 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
1fe30 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
1fe40 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
1fe50 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
1fe60 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
1fe70 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
1fe80 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
1fe90 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
1fea0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
1feb0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
1fec0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
1fed0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
1fee0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
1fef0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
1ff00 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
1ff10 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
1ff20 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
1ff30 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
1ff40 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
1ff50 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
1ff60 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
1ff70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1ff80 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
1ff90 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
1ffa0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
1ffb0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
1ffc0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
1ffd0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
1ffe0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
1fff0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
20000 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
20010 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
20020 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
20030 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
20040 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
20050 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
20060 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
20070 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
20080 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
20090 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
200a0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
200b0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
200c0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
200d0 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
200e0 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ta..**.** [SQLIT
200f0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
20100 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
20110 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
20120 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
20130 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
20140 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
20150 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
20160 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
20170 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
20180 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
20190 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
201a0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
201b0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
201c0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
201d0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
201e0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
201f0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
20200 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
20210 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
20220 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
20230 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
20240 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
20250 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
20260 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
20270 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
20280 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
20290 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
202a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
202b0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
202c0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
202d0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
202e0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
202f0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
20300 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
20310 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
20320 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
20330 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
20340 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
20350 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
20360 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
20370 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
20380 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
20390 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
203a0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
203b0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
203c0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
203d0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
203e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
203f0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
20400 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
20410 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
20420 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
20430 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
20440 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
20450 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
20460 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
20470 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
20480 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
20490 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
204a0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
204b0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
204c0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
204d0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
204e0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
204f0 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
20500 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
20510 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
20520 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
20530 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
20540 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
20550 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
20560 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
20570 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
20580 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
20590 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
205a0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
205b0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
205c0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
205d0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
205e0 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
205f0 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
20600 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
20610 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
20620 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
20630 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
20640 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
20650 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
20660 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
20670 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
20680 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
20690 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
206a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
206b0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
206c0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
206d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
206e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
206f0 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
20700 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
20710 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
20720 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
20730 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
20740 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
20750 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
20760 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
20770 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
20780 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
20790 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
207a0 2a 20 5b 48 31 33 32 30 32 5d 20 5b 48 31 35 33  * [H13202] [H153
207b0 30 34 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48 31  04] [H15306] [H1
207c0 35 33 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a 2a  5308] [H15310].*
207d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
207e0 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
207f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20800 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
20810 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
20820 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c  t set {H13770} <
20830 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S10700>.**.** Re
20840 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
20850 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68   of values in th
20860 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
20870 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e   the result set.
20880 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
20890 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 31 5d  nts:.** [H13771]
208a0 20 5b 48 31 33 37 37 32 5d 0a 2a 2f 0a 69 6e 74   [H13772].*/.int
208b0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
208c0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
208d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
208e0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
208f0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
20900 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31   {H10265} <S1011
20910 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45  0><S10120>.** KE
20920 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
20930 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36  EXT.**.** {H1026
20940 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69  6} Every value i
20950 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
20960 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
20970 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
20980 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
20990 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
209a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
209b0 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
209c0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
209d0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
209e0 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
209f0 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
20a00 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  /ul> {END}.**.**
20a10 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
20a20 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
20a30 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
20a40 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
20a50 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
20a60 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
20a70 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
20a80 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
20a90 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
20aa0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
20ab0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
20ac0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
20ad0 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
20ae0 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
20af0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
20b00 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
20b10 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
20b20 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
20b30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20b40 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
20b50 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
20b60 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
20b70 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
20b80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
20b90 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
20ba0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
20bb0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
20bc0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
20bd0 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
20be0 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
20bf0 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
20c00 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
20c10 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
20c20 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b  s From A Query {
20c30 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e  H13800} <S10700>
20c40 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
20c50 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
20c60 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
20c70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
20c80 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
20c90 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61  t query" interfa
20ca0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ce..**.** These 
20cb0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
20cc0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
20cd0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
20ce0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
20cf0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
20d00 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65  f a query.  In e
20d10 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
20d20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
20d30 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
20d40 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
20d50 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
20d60 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
20d70 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
20d80 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
20d90 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
20da0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20db0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
20dc0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
20dd0 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
20de0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
20df0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
20e00 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
20e10 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
20e20 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
20e30 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  .  The leftmost 
20e40 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
20e50 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
20e60 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20   index 0..**.** 
20e70 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
20e80 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
20e90 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
20ea0 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
20eb0 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
20ec0 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
20ed0 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
20ee0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
20ef0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
20f00 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
20f10 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
20f20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
20f30 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
20f40 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
20f50 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
20f60 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
20f70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
20f80 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
20f90 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
20fa0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
20fb0 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
20fc0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
20fd0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
20fe0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
20ff0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
21000 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21010 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
21020 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
21030 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
21040 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
21050 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
21060 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
21070 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
21080 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
21090 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
210a0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
210b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
210c0 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
210d0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
210e0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
210f0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
21100 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
21110 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
21120 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
21130 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
21140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
21150 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
21160 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
21170 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
21180 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
21190 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
211a0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
211b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54  esult column.  T
211c0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
211d0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
211e0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
211f0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
21200 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
21210 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
21220 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
21230 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
21240 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
21250 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
21260 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
21270 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
21280 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
21290 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
212a0 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
212b0 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
212c0 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
212d0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
212e0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
212f0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
21300 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
21310 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
21320 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
21330 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
21340 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21350 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
21360 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
21370 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  sion..**.** If t
21380 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
21390 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
213a0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
213b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
213c0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
213d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
213e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
213f0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
21400 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  g..** If the res
21410 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
21420 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
21430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21440 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
21450 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
21460 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
21470 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
21480 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20  of bytes..** If 
21490 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
214a0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
214b0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
214c0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
214d0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
214e0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
214f0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
21500 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
21510 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
21520 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
21530 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
21540 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72  ..** The value r
21550 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
21560 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
21570 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o terminator at 
21580 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
21590 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63  e string.  For c
215a0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
215b0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  e returned is th
215c0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
215d0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
215e0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
215f0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
21600 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20  ..**.** Strings 
21610 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
21620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
21630 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
21640 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
21650 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
21660 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
21670 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
21680 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a  .  The return.**
21690 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
216a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
216b0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
216c0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61  gth BLOB is an a
216d0 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e  rbitrary.** poin
216e0 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76  ter, possibly ev
216f0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
21700 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
21710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21720 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73  s16() routine is
21730 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69   similar to sqli
21740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
21750 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73  ().** but leaves
21760 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55   the result in U
21770 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20  TF-16 in native 
21780 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
21790 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20  ad of UTF-8..** 
217a0 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  The zero termina
217b0 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  tor is not inclu
217c0 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  ded in this coun
217d0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a  t..**.** The obj
217e0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
217f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
21800 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
21810 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
21820 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
21830 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
21840 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
21850 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
21860 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
21870 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
21880 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
21890 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
218a0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
218b0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
218c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
218d0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
218e0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
218f0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
21900 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
21910 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
21920 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
21930 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
21940 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
21950 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
21960 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
21970 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
21980 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
21990 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
219a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
219b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
219c0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
219d0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
219e0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
219f0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
21a00 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
21a10 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
21a20 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
21a30 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
21a40 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
21a50 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
21a60 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
21a70 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
21a80 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
21a90 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
21aa0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
21ab0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
21ac0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
21ad0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
21ae0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
21af0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
21b00 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
21b10 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
21b20 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
21b30 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
21b40 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
21b50 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
21b60 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
21b70 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
21b80 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
21b90 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
21ba0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
21bb0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
21bc0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
21bd0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
21be0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
21bf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
21c00 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
21c10 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
21c20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
21c30 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
21c40 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
21c50 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
21c60 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
21c70 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
21c80 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
21c90 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
21ca0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
21cb0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
21cc0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
21cd0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
21ce0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
21cf0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
21d00 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
21d10 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
21d20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
21d30 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
21d40 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
21d50 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
21d60 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
21d70 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
21d80 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
21d90 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
21da0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
21db0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
21dc0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
21dd0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
21de0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
21df0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
21e00 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
21e10 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
21e20 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
21e30 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
21e40 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
21e50 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
21e60 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
21e70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
21e80 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
21e90 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
21ea0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
21eb0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
21ec0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
21ed0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
21ee0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
21ef0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
21f00 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
21f10 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
21f20 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
21f30 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
21f40 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
21f50 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
21f60 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
21f70 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
21f80 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
21f90 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
21fa0 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
21fb0 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
21fc0 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
21fd0 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
21fe0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
21ff0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
22000 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
22010 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
22020 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
22030 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
22040 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
22050 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
22060 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
22070 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
22080 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
22090 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
220a0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
220b0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
220c0 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
220d0 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
220e0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
220f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22100 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
22110 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
22120 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
22130 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
22140 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
22150 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
22160 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
22170 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
22180 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
22190 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
221a0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
221b0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
221c0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
221d0 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
221e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
221f0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
22200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22210 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
22220 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
22230 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
22240 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
22250 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
22260 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
22270 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
22280 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
22290 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
222a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
222b0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
222c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
222d0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
222e0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
222f0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
22300 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
22310 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
22320 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
22330 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
22340 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
22350 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
22360 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
22370 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
22380 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
22390 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
223a0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
223b0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
223c0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
223d0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
223e0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
223f0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
22400 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
22410 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
22420 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
22430 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
22440 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
22450 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
22460 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
22470 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
22480 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
22490 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
224a0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
224b0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
224c0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
224d0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
224e0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
224f0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
22500 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
22510 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
22520 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
22530 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
22540 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
22550 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
22560 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
22570 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
22580 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
22590 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
225a0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
225b0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
225c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
225d0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
225e0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
225f0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
22600 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
22610 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
22620 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
22630 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
22640 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
22650 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
22660 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
22670 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22680 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
22690 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
226a0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
226b0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
226c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
226d0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
226e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
226f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22700 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
22710 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
22720 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
22730 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
22740 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
22750 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
22760 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
22770 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
22780 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
22790 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
227a0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
227b0 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
227c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
227d0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
227e0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
227f0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
22800 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
22810 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
22820 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
22830 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
22840 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
22850 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
22860 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
22870 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72  * The pointers r
22880 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
22890 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
228a0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
228b0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
228c0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
228d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
228e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
228f0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
22900 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22910 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ] is called.  Th
22920 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
22930 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
22940 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
22950 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
22960 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
22970 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
22980 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
22990 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
229a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
229b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
229c0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
229d0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
229e0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ee()]..**.** If 
229f0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
22a00 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
22a10 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
22a20 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
22a30 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
22a40 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
22a50 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
22a60 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
22a70 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
22a80 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
22a90 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
22aa0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
22ab0 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
22ac0 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
22ad0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
22ae0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
22af0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
22b00 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
22b10 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
22b20 0a 2a 2a 20 5b 48 31 33 38 30 33 5d 20 5b 48 31  .** [H13803] [H1
22b30 33 38 30 36 5d 20 5b 48 31 33 38 30 39 5d 20 5b  3806] [H13809] [
22b40 48 31 33 38 31 32 5d 20 5b 48 31 33 38 31 35 5d  H13812] [H13815]
22b50 20 5b 48 31 33 38 31 38 5d 20 5b 48 31 33 38 32   [H13818] [H1382
22b60 31 5d 20 5b 48 31 33 38 32 34 5d 0a 2a 2a 20 5b  1] [H13824].** [
22b70 48 31 33 38 32 37 5d 20 5b 48 31 33 38 33 30 5d  H13827] [H13830]
22b80 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
22b90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
22ba0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
22bb0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
22bc0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
22bd0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
22be0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
22bf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
22c00 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
22c10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
22c20 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
22c30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
22c40 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
22c50 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
22c60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22c70 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
22c80 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
22c90 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
22ca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
22cb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22cc0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
22cd0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
22ce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22cf0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
22d00 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
22d10 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
22d20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
22d30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22d40 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
22d50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
22d60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
22d70 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
22d80 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
22d90 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
22da0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22db0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
22dc0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
22dd0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
22de0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
22df0 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13300} <S70300>
22e00 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
22e10 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
22e20 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
22e30 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
22e40 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
22e50 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
22e60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
22e70 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63  as executed succ
22e80 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20  essfully or not 
22e90 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c  executed at all,
22ea0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f   then.** SQLITE_
22eb0 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OK is returned. 
22ec0 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
22ed0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
22ee0 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20  iled then an.** 
22ef0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
22f00 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
22f10 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
22f20 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
22f30 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
22f40 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
22f50 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63   during the exec
22f60 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ution of the.** 
22f70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22f80 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69  ent].  If the vi
22f90 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
22fa0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s not.** complet
22fb0 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65  ed execution whe
22fc0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  n this routine i
22fd0 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69  s called, that i
22fe0 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e  s like.** encoun
22ff0 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
23000 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  or an [sqlite3_i
23010 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
23020 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70  rupt]..** Incomp
23030 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79  lete updates may
23040 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
23050 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  and transactions
23060 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65   canceled,.** de
23070 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
23080 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e  ircumstances, an
23090 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20  d the.** [error 
230a0 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77  code] returned w
230b0 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  ill be [SQLITE_A
230c0 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  BORT]..**.** Req
230d0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
230e0 31 31 33 30 32 5d 20 5b 48 31 31 33 30 34 5d 0a  11302] [H11304].
230f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
23100 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
23110 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
23120 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
23130 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
23140 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
23150 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30   {H13330} <S7030
23160 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
23170 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
23180 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
23190 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
231a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
231b0 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
231c0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
231d0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
231e0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
231f0 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
23200 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
23210 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
23220 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
23230 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
23240 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
23250 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
23260 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
23270 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
23280 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
23290 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
232a0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
232b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20  .**.** {H11332} 
232c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
232d0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
232e0 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
232f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23300 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   S.**          b
23310 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
23320 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
23330 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ram..**.** {H113
23340 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  34} If the most 
23350 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
23360 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
23370 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
23380 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
23390 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
233a0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
233b0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
233c0 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E],.**          
233d0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
233e0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
233f0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
23400 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20  lled on S,.**   
23410 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
23420 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
23430 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
23440 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  K]..**.** {H1133
23450 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  6} If the most r
23460 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
23470 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
23480 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
23490 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
234a0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
234b0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
234c0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
234d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
234e0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
234f0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
23500 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48   code]..**.** {H
23510 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69  11338} The [sqli
23520 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
23530 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
23540 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
23550 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
23560 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
23570 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
23580 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
23590 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
235a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
235b0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
235c0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
235d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
235e0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
235f0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b   SQL Functions {
23600 48 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e  H16100} <S20200>
23610 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
23620 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
23630 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
23640 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
23650 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
23660 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
23670 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
23680 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
23690 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
236a0 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63  * These two func
236b0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
236c0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
236d0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
236e0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
236f0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
23700 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
23710 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
23720 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
23730 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
23740 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
23750 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
23760 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
23770 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74  erence between t
23780 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61  he.** two is tha
23790 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  t the second par
237a0 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65  ameter, the name
237b0 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29   of the (scalar)
237c0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
237d0 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e  aggregate, is en
237e0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66  coded in UTF-8 f
237f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
23800 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
23810 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73   UTF-16.** for s
23820 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
23830 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  nction16()..**.*
23840 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
23850 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
23860 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23870 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
23880 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
23890 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
238a0 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f   If a single pro
238b0 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74  gram uses more t
238c0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
238d0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
238e0 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20  nternally, then 
238f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
23900 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69  st be added indi
23910 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65  vidually to.** e
23920 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
23930 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  nection..**.** T
23940 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
23950 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
23960 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
23970 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
23980 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
23990 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f  d.  The length o
239a0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
239b0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
239c0 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
239d0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72  .** the zero-ter
239e0 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
239f0 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
23a00 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
23a10 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
23a20 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61  aracters.  Any a
23a30 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
23a40 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
23a50 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
23a60 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
23a70 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
23a80 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
23a90 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
23aa0 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
23ab0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
23ac0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
23ad0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
23ae0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
23af0 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74  gate takes. If t
23b00 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
23b10 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
23b20 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
23b30 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
23b40 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
23b50 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
23b60 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
23b70 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
23b80 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
23b90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
23ba0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
23bb0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
23bc0 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
23bd0 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
23be0 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
23bf0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
23c00 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
23c10 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
23c20 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
23c30 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
23c40 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
23c50 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
23c60 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
23c70 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
23c80 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
23c90 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75  ers.  Any SQL fu
23ca0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
23cb0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ation should be 
23cc0 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
23cd0 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c  work with UTF-8,
23ce0 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
23cf0 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
23d00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
23d10 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
23d20 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
23d30 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
23d40 6e 20 61 6e 6f 74 68 65 72 2e 20 20 41 6e 20 61  n another.  An a
23d50 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
23d60 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
23d70 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
23d80 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
23d90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
23da0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
23db0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
23dc0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
23dd0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
23de0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
23df0 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70  ..** When multip
23e00 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
23e10 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
23e20 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
23e30 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
23e40 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
23e50 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
23e60 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
23e70 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
23e80 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
23e90 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
23ea0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
23eb0 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
23ec0 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a   care what text.
23ed0 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  ** encoding is u
23ee0 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
23ef0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
23f00 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f  ould be [SQLITE_
23f10 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ANY]..**.** The 
23f20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
23f30 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
23f40 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
23f50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
23f60 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
23f70 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
23f80 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
23f90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
23fa0 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a  ser_data()]..**.
23fb0 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20  ** The seventh, 
23fc0 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68  eighth and ninth
23fd0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
23fe0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
23ff0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
24000 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
24010 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
24020 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
24030 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
24040 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41  .** aggregate. A
24050 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
24060 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
24070 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
24080 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
24090 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e  callback only, N
240a0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f  ULL pointers sho
240b0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73  uld be passed as
240c0 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
240d0 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
240e0 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74  ers. An aggregat
240f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
24100 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
24110 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
24120 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
24130 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64   and NULL should
24140 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
24150 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20  Func. To delete 
24160 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
24170 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
24180 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
24190 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ULL for all thre
241a0 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  e function callb
241b0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  acks..**.** It i
241c0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
241d0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
241e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
241f0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
24200 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
24210 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
24220 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
24230 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
24240 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
24250 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
24260 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
24270 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69  ings.  SQLite wi
24280 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
24290 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
242a0 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
242b0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
242c0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
242d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
242e0 73 65 64 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e  sed.  A function
242f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
24300 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
24310 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
24320 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
24330 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
24340 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
24350 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
24360 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
24370 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   A function wher
24380 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
24390 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
243a0 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
243b0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
243c0 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
243d0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
243e0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
243f0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
24400 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e 63  ent.  .** A func
24410 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
24420 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
24430 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
24440 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
24450 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
24460 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
24470 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
24480 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
24490 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
244a0 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
244b0 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69  6..**.** Built-i
244c0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
244d0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
244e0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
244f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
24500 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ns..** The first
24510 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
24520 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69  ined function wi
24530 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20  th a given name 
24540 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a  overrides all.**
24550 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69   built-in functi
24560 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20  ons in the same 
24570 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24580 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73  tion] with the s
24590 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62  ame name..** Sub
245a0 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74  sequent applicat
245b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
245c0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
245d0 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72  e name only over
245e0 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61  ride .** prior a
245f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
24600 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ed functions tha
24610 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d  t are an exact m
24620 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20  atch for the.** 
24630 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
24640 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72 72  ters and preferr
24650 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  ed encoding..**.
24660 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** An applicatio
24670 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
24680 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
24690 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
246a0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
246b0 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
246c0 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
246d0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
246e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
246f0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
24700 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
24710 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
24720 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
24730 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
24740 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
24750 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
24760 31 30 33 5d 20 5b 48 31 36 31 30 36 5d 20 5b 48  103] [H16106] [H
24770 31 36 31 30 39 5d 20 5b 48 31 36 31 31 32 5d 20  16109] [H16112] 
24780 5b 48 31 36 31 31 38 5d 20 5b 48 31 36 31 32 31  [H16118] [H16121
24790 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 20 5b 48  ] [H16127].** [H
247a0 31 36 31 33 30 5d 20 5b 48 31 36 31 33 33 5d 20  16130] [H16133] 
247b0 5b 48 31 36 31 33 36 5d 20 5b 48 31 36 31 33 39  [H16136] [H16139
247c0 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 0a 69 6e  ] [H16142].*/.in
247d0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
247e0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
247f0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
24800 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
24810 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
24820 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
24830 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
24840 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
24850 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
24860 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
24870 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
24880 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
24890 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
248a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
248b0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
248c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
248d0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
248e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
248f0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
24900 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
24910 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
24920 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
24930 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
24940 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
24950 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
24960 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
24970 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
24980 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
24990 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
249a0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
249b0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
249c0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
249d0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
249e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
249f0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48  ext Encodings {H
24a00 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20  10267} <S50200> 
24a10 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H16100>.**.** T
24a20 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
24a30 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
24a40 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
24a50 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
24a60 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
24a70 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
24a80 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
24a90 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
24aa0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
24ab0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
24ac0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
24ad0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
24ae0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
24af0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
24b00 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
24b10 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
24b20 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
24b30 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
24b40 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
24b50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24b60 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
24b70 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
24b80 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
24b90 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
24ba0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
24bb0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
24bc0 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
24bd0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
24be0 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
24bf0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
24c00 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
24c10 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
24c20 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
24c30 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
24c40 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
24c50 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
24c60 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
24c70 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
24c80 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
24c90 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
24ca0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
24cb0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
24cc0 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
24cd0 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
24ce0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
24cf0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
24d00 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
24d10 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
24d20 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
24d30 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
24d40 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
24d50 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
24d60 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
24d70 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
24d80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
24d90 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
24da0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
24db0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
24dc0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
24dd0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
24de0 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
24df0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
24e00 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
24e10 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
24e20 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
24e30 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
24e40 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
24e50 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
24e60 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
24e70 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
24e80 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
24e90 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
24ea0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
24eb0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
24ec0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
24ed0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
24ee0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
24ef0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
24f00 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
24f10 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
24f20 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32  s {H15100} <S202
24f30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  00>.**.** The C-
24f40 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
24f50 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
24f60 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
24f70 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
24f80 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
24f90 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
24fa0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
24fb0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
24fc0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
24fd0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
24fe0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
24ff0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
25000 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
25010 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
25020 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
25030 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
25040 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
25050 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
25060 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
25070 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
25080 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
25090 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
250a0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
250b0 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
250c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
250d0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
250e0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
250f0 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
25100 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25110 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
25120 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
25130 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
25140 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
25150 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
25160 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
25170 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
25180 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
25190 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
251a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
251b0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
251c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
251d0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
251e0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
251f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
25200 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
25210 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
25220 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
25230 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
25240 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
25250 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
25260 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
25270 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
25280 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
25290 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
252a0 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
252b0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
252c0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
252d0 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
252e0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
252f0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
25300 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
25310 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
25320 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
25330 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
25340 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
25350 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
25360 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
25370 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
25380 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
25390 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
253a0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
253b0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
253c0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
253d0 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ine.  The.** sql
253e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
253f0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
25400 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
25410 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
25420 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
25430 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
25440 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
25450 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
25460 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  vely..**.** The 
25470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
25480 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
25490 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
254a0 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
254b0 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
254c0 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
254d0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
254e0 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
254f0 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
25500 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
25510 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
25520 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
25530 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
25540 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
25550 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
25560 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
25570 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
25580 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
25590 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
255a0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
255b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
255c0 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
255d0 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
255e0 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
255f0 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
25600 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
25610 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
25620 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
25630 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65  urned..**.** Ple
25640 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
25650 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
25660 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
25670 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
25680 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
25690 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
256a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
256b0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
256c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
256d0 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
256e0 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
256f0 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
25700 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
25710 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
25720 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
25730 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
25740 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
25750 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
25760 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
25770 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
25780 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
25790 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
257a0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
257b0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
257c0 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
257d0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
257e0 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
257f0 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
25800 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 35 31 30  ments:.** [H1510
25810 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 48 31 35  3] [H15106] [H15
25820 31 30 39 5d 20 5b 48 31 35 31 31 32 5d 20 5b 48  109] [H15112] [H
25830 31 35 31 31 35 5d 20 5b 48 31 35 31 31 38 5d 20  15115] [H15118] 
25840 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 31 32 34  [H15121] [H15124
25850 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 20 5b 48  ].** [H15127] [H
25860 31 35 31 33 30 5d 20 5b 48 31 35 31 33 33 5d 20  15130] [H15133] 
25870 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 6f 6e 73  [H15136].*/.cons
25880 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
25890 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
258a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
258b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
258c0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
258d0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
258e0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
258f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
25900 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
25910 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
25920 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
25930 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
25940 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
25950 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
25960 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
25970 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
25980 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
25990 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
259a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
259b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
259c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
259d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
259e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
259f0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
25a00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25a10 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
25a20 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
25a30 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
25a40 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
25a50 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
25a60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
25a70 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
25a80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
25a90 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
25aa0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
25ab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25ac0 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
25ad0 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
25ae0 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53  text {H16210} <S
25af0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
25b00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25b10 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
25b20 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
25b30 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  his routine to a
25b40 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72  llocate.** a str
25b50 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69  ucture for stori
25b60 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
25b70 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
25b80 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
25b90 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
25ba0 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  xt() routine is 
25bb0 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20  called for a.** 
25bc0 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
25bd0 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c  gate, SQLite all
25be0 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66  ocates nBytes of
25bf0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
25c00 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f  out that.** memo
25c10 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
25c20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
25c30 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73   On second and s
25c40 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
25c50 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
25c60 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
25c70 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
25c80 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
25c90 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20  n index,.** the 
25ca0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
25cb0 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70  eturned. The imp
25cc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
25cd0 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
25ce0 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75   use.** the retu
25cf0 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61  rned buffer to a
25d00 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a  ccumulate data..
25d10 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74  **.** SQLite aut
25d20 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
25d30 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   the allocated b
25d40 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61  uffer when the a
25d50 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72  ggregate.** quer
25d60 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
25d70 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
25d80 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
25d90 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
25da0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
25db0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
25dc0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
25dd0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
25de0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
25df0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
25e00 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
25e10 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  s the aggregate 
25e20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
25e30 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
25e40 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
25e50 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
25e60 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
25e70 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
25e80 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
25e90 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ng..**.** Requir
25ea0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32  ements:.** [H162
25eb0 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 5b 48 31  11] [H16213] [H1
25ec0 36 32 31 35 5d 20 5b 48 31 36 32 31 37 5d 0a 2a  6215] [H16217].*
25ed0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
25ee0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
25ef0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
25f00 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
25f10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25f20 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
25f30 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34  Functions {H1624
25f40 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S20200>.**.*
25f50 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73  * The sqlite3_us
25f60 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
25f70 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
25f80 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
25f90 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
25fa0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
25fb0 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
25fc0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
25fd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
25fe0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
25ff0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
26000 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
26010 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
26020 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
26030 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
26040 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
26050 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45  ned function. {E
26060 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ND}.**.** This r
26070 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
26080 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
26090 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
260a0 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
260b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
260c0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
260d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ng..**.** Requir
260e0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32  ements:.** [H162
260f0 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  43].*/.void *sql
26100 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
26110 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
26120 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26130 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
26140 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
26150 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53  ions {H16250} <S
26160 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a  60600><S20200>.*
26170 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26180 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
26190 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
261a0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
261b0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
261c0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
261d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
261e0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
261f0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
26200 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26210 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
26220 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26230 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
26240 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
26250 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
26260 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
26270 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
26280 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ion..**.** Requi
26290 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
262a0 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  253].*/.sqlite3 
262b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
262c0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
262d0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
262e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
262f0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
26300 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20  y Data {H16270} 
26310 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
26320 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
26330 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
26340 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72  e used by scalar
26350 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
26360 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
26370 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
26380 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
26390 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
263a0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
263b0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
263c0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
263d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
263e0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
263f0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
26400 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
26410 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
26420 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
26430 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
26440 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
26450 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
26460 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
26470 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
26480 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
26490 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
264a0 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
264b0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
264c0 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
264d0 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
264e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
264f0 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
26500 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
26510 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
26520 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
26530 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
26540 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
26550 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
26560 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
26570 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
26580 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
26590 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
265a0 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
265b0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
265c0 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
265d0 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
265e0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
265f0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
26600 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
26610 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
26620 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
26630 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
26640 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
26650 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
26660 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
26670 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
26680 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
26690 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
266a0 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74  ction. If no met
266b0 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65  adata has been e
266c0 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20  ver.** been set 
266d0 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75  for the Nth argu
266e0 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63  ment of the func
266f0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20  tion, or if the 
26700 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
26710 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
26720 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20  ter has changed 
26730 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64  since the meta-d
26740 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20  ata was set,.** 
26750 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  then sqlite3_get
26760 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72  _auxdata() retur
26770 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
26780 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
26790 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
267a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  () interface sav
267b0 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  es the metadata.
267c0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
267d0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
267e0 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61  er as the metada
267f0 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
26800 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
26810 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
26820 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
26830 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
26840 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
26850 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
26860 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
26870 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
26880 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
26890 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74  troyed..** If it
268a0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
268b0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
268c0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
268d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
268e0 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
268f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
26900 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
26910 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61  on.** the metada
26920 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
26930 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
26940 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
26950 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
26960 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
26970 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
26980 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
26990 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
269a0 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
269b0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
269c0 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74  and drop metadat
269d0 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61  a on any.** para
269e0 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
269f0 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
26a00 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61  e.  The only gua
26a10 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
26a20 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
26a30 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
26a40 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
26a50 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
26a60 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63  **.** In practic
26a70 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
26a80 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
26a90 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
26aa0 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
26ab0 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
26ac0 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
26ad0 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
26ae0 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
26af0 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61  alues and SQL va
26b00 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  riables..**.** T
26b10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
26b20 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
26b30 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
26b40 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
26b50 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
26b60 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
26b70 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
26b80 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 31 36 32  * [H16272] [H162
26b90 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 5b 48 31  74] [H16276] [H1
26ba0 36 32 37 37 5d 20 5b 48 31 36 32 37 38 5d 20 5b  6277] [H16278] [
26bb0 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f 69 64 20  H16279].*/.void 
26bc0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
26bd0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
26be0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
26bf0 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
26c00 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
26c10 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
26c20 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
26c30 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
26c40 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
26c50 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
26c60 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
26c70 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32  r Behavior {H102
26c80 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  80} <S30100>.**.
26c90 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
26ca0 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
26cb0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
26cc0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
26cd0 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
26ce0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
26cf0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
26d00 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
26d10 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74  )].  If the dest
26d20 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
26d30 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
26d40 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
26d50 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
26d60 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
26d70 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
26d80 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
26d90 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
26da0 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
26db0 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   The.** SQLITE_T
26dc0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
26dd0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
26de0 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
26df0 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
26e00 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
26e10 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
26e20 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
26e30 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
26e40 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
26e50 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
26e60 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
26e70 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
26e80 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
26e90 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
26ea0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
26eb0 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
26ec0 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
26ed0 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
26ee0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
26ef0 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
26f00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
26f10 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
26f20 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
26f30 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
26f40 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
26f50 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
26f60 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
26f70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26f80 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
26f90 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
26fa0 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c  ction {H16400} <
26fb0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
26fc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
26fd0 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
26fe0 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
26ff0 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
27000 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
27010 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
27020 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
27030 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27040 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
27050 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27060 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
27070 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
27080 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
27090 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
270a0 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
270b0 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
270c0 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
270d0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
270e0 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
270f0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
27100 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
27110 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27120 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
27130 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
27140 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
27150 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
27160 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
27170 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27180 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
27190 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
271a0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
271b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
271c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
271d0 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
271e0 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
271f0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
27200 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
27210 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
27220 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
27230 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
27240 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
27250 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
27260 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
27270 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
27280 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
27290 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
272a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
272b0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
272c0 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
272d0 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
272e0 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
272f0 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
27300 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
27310 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
27320 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
27330 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
27340 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
27350 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
27360 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
27370 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
27380 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
27390 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
273a0 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
273b0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
273c0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
273d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
273e0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
273f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
27400 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
27410 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
27420 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
27430 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
27440 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
27450 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
27460 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
27470 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
27480 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
27490 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
274a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
274b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
274c0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
274d0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
274e0 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
274f0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
27500 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
27510 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
27520 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
27530 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20  TF-8. SQLite.** 
27540 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
27550 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
27560 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
27570 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
27580 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
27590 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74  order.  If the t
275a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
275b0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
275c0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
275d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
275e0 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
275f0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
27600 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
27610 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
27620 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
27630 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
27640 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
27650 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
27660 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
27670 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
27680 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
27690 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
276a0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
276b0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
276c0 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
276d0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
276e0 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
276f0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
27700 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
27710 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
27720 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
27730 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
27740 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
27750 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
27760 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
27770 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27780 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
27790 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
277a0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
277b0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
277c0 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
277d0 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
277e0 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
277f0 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
27800 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
27810 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
27820 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
27830 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
27840 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
27850 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
27860 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
27870 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
27880 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20   By default,.** 
27890 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
278a0 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
278b0 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   A subsequent ca
278c0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
278d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
278e0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
278f0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
27900 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
27910 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
27920 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  R..**.** The sql
27930 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
27940 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
27950 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
27960 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
27970 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
27980 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
27990 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f  OB is to long to
279a0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
279b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
279c0 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
279d0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
279e0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
279f0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
27a00 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
27a10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
27a20 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  iled..**.** The 
27a30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
27a40 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
27a50 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
27a60 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
27a70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27a80 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
27a90 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
27aa0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
27ab0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
27ac0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
27ad0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
27ae0 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
27af0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
27b00 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
27b10 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
27b20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
27b30 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
27b40 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
27b50 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
27b60 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
27b70 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
27b80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27b90 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
27ba0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
27bb0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
27bc0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
27bd0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
27be0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
27bf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
27c00 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
27c10 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
27c20 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
27c30 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
27c40 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
27c50 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
27c60 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
27c70 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
27c80 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
27c90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27ca0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
27cb0 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
27cc0 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
27cd0 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
27ce0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
27cf0 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
27d00 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
27d10 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
27d20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
27d30 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  vely..** SQLite 
27d40 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
27d50 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
27d60 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
27d70 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
27d80 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
27d90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
27da0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
27db0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
27dc0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
27dd0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
27de0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
27df0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
27e00 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
27e10 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
27e20 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
27e30 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
27e40 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
27e50 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
27e60 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
27e70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
27e80 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
27e90 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
27ea0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
27eb0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
27ec0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
27ed0 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
27ee0 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
27ef0 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
27f00 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
27f10 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
27f20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
27f30 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
27f40 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
27f50 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
27f60 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
27f70 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
27f80 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
27f90 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
27fa0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
27fb0 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
27fc0 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
27fd0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
27fe0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
27ff0 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
28000 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
28010 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
28020 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
28030 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
28040 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
28050 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
28060 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
28070 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
28080 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
28090 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
280a0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
280b0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
280c0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
280d0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
280e0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
280f0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
28100 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
28110 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
28120 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
28130 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
28140 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
28150 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
28160 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
28170 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
28180 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
28190 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
281a0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
281b0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
281c0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
281d0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
281e0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
281f0 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
28200 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
28210 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
28220 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
28230 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
28240 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
28250 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
28260 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
28270 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
28280 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
28290 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
282a0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
282b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
282c0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
282d0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
282e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
282f0 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
28300 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
28310 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a  arameter.  The.*
28320 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
28330 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
28340 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
28350 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
28360 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
28370 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
28380 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
28390 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
283a0 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
283b0 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
283c0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
283d0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
283e0 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
283f0 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63  rm..** A [protec
28400 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28410 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
28420 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
28430 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
28440 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28450 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
28460 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
28470 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
28480 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28490 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
284a0 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
284b0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
284c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
284d0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
284e0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
284f0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
28500 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
28510 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
28520 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
28530 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
28540 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
28550 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
28560 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
28570 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
28580 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
28590 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 34 30 33 5d  nts:.** [H16403]
285a0 20 5b 48 31 36 34 30 36 5d 20 5b 48 31 36 34 30   [H16406] [H1640
285b0 39 5d 20 5b 48 31 36 34 31 32 5d 20 5b 48 31 36  9] [H16412] [H16
285c0 34 31 35 5d 20 5b 48 31 36 34 31 38 5d 20 5b 48  415] [H16418] [H
285d0 31 36 34 32 31 5d 20 5b 48 31 36 34 32 34 5d 0a  16421] [H16424].
285e0 2a 2a 20 5b 48 31 36 34 32 37 5d 20 5b 48 31 36  ** [H16427] [H16
285f0 34 33 30 5d 20 5b 48 31 36 34 33 33 5d 20 5b 48  430] [H16433] [H
28600 31 36 34 33 36 5d 20 5b 48 31 36 34 33 39 5d 20  16436] [H16439] 
28610 5b 48 31 36 34 34 32 5d 20 5b 48 31 36 34 34 35  [H16442] [H16445
28620 5d 20 5b 48 31 36 34 34 38 5d 0a 2a 2a 20 5b 48  ] [H16448].** [H
28630 31 36 34 35 31 5d 20 5b 48 31 36 34 35 34 5d 20  16451] [H16454] 
28640 5b 48 31 36 34 35 37 5d 20 5b 48 31 36 34 36 30  [H16457] [H16460
28650 5d 20 5b 48 31 36 34 36 33 5d 0a 2a 2f 0a 76 6f  ] [H16463].*/.vo
28660 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
28670 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
28680 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
28690 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
286a0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
286b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
286c0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
286d0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
286e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
286f0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
28700 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
28710 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
28720 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
28730 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
28740 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
28750 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
28760 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
28770 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
28780 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
28790 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
287a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
287b0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
287c0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
287d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
287e0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
287f0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
28800 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
28810 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
28820 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
28830 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
28840 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
28850 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
28860 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
28870 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28880 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
28890 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
288a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
288b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
288c0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
288d0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
288e0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
288f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
28900 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28910 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
28920 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
28930 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
28940 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
28950 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
28960 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
28970 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
28980 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
28990 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
289a0 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
289b0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
289c0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
289d0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
289e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
289f0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
28a00 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
28a10 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
28a20 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
28a30 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
28a40 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
28a50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
28a60 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
28a70 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36  g Sequences {H16
28a80 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a  600} <S20300>.**
28a90 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
28aa0 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
28ab0 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
28ac0 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
28ad0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
28ae0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
28af0 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
28b00 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
28b10 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
28b20 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  he new collation
28b30 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65   sequence is spe
28b40 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d  cified as a UTF-
28b50 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
28b60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
28b70 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
28b80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
28b90 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
28ba0 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
28bb0 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ing for sqlite3_
28bc0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
28bd0 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73  16(). In all cas
28be0 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
28bf0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
28c00 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
28c10 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
28c20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
28c30 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nt may be one of
28c40 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
28c50 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
28c60 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
28c70 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
28c80 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16BE], indicati
28c90 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72  ng that the user
28ca0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75  -supplied.** rou
28cb0 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20  tine expects to 
28cc0 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65  be passed pointe
28cd0 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e  rs to strings en
28ce0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
28cf0 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  8,.** UTF-16 lit
28d00 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle-endian, or U
28d10 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
28d20 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
28d30 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  The.** third arg
28d40 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f  ument might also
28d50 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
28d60 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  6] to indicate t
28d70 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a  hat the routine.
28d80 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ** expects point
28d90 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36  ers to be UTF-16
28da0 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
28db0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
28dc0 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67  r, or the.** arg
28dd0 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51  ument can be [SQ
28de0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
28df0 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68  ED] if the.** th
28e00 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
28e10 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
28e20 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
28e30 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
28e40 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
28e50 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
28e60 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
28e70 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
28e80 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
28e90 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
28ea0 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
28eb0 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73  ument.  If it is
28ec0 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74   NULL, this is t
28ed0 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74  he same as delet
28ee0 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  ing the collatio
28ef0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73  n.** sequence (s
28f00 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  o that SQLite ca
28f10 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79  nnot call it any
28f20 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74  more)..** Each t
28f30 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
28f40 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e  ion supplied fun
28f50 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
28f60 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a  , it is passed.*
28f70 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  * as its first p
28f80 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20  arameter a copy 
28f90 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73  of the void* pas
28fa0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
28fb0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
28fc0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
28fd0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73  collation() or s
28fe0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
28ff0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  llation16()..**.
29000 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
29010 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
29020 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  e application-su
29030 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61  pplied routine a
29040 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a  re two strings,.
29050 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e  ** each represen
29060 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68  ted by a (length
29070 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64  , data) pair and
29080 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20   encoded in the 
29090 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74  encoding.** that
290a0 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74   was passed as t
290b0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
290c0 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  t when the colla
290d0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61  tion sequence wa
290e0 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e  s.** registered.
290f0 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c   {END}  The appl
29100 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
29110 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e  collation routin
29120 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  e should.** retu
29130 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  rn negative, zer
29140 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66  o or positive if
29150 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
29160 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a  g is less than,.
29170 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  ** equal to, or 
29180 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
29190 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20   second string. 
291a0 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20  i.e. (STRING1 - 
291b0 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20  STRING2)..**.** 
291c0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
291d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
291e0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
291f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
29200 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70  ation().** excep
29210 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
29220 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
29230 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
29240 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
29250 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54  he collation.  T
29260 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
29270 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
29280 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a   collation is.**
29290 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69   destroyed and i
292a0 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20  s passed a copy 
292b0 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
292c0 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f  rameter void* po
292d0 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20  inter.** of the 
292e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
292f0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  ollation_v2()..*
29300 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65  * Collations are
29310 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20   destroyed when 
29320 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
29330 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
29340 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c  ls to the.** col
29350 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
29360 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
29370 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
29380 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
29390 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  losed.** using [
293a0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
293b0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
293c0 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
293d0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
293e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
293f0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
29400 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  )]..**.** Requir
29410 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 36  ements:.** [H166
29420 30 33 5d 20 5b 48 31 36 36 30 34 5d 20 5b 48 31  03] [H16604] [H1
29430 36 36 30 36 5d 20 5b 48 31 36 36 30 39 5d 20 5b  6606] [H16609] [
29440 48 31 36 36 31 32 5d 20 5b 48 31 36 36 31 35 5d  H16612] [H16615]
29450 20 5b 48 31 36 36 31 38 5d 20 5b 48 31 36 36 32   [H16618] [H1662
29460 31 5d 0a 2a 2a 20 5b 48 31 36 36 32 34 5d 20 5b  1].** [H16624] [
29470 48 31 36 36 32 37 5d 20 5b 48 31 36 36 33 30 5d  H16627] [H16630]
29480 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29490 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
294a0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
294b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
294c0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
294d0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
294e0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
294f0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
29500 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
29510 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
29520 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
29530 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
29540 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
29550 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
29560 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
29570 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
29580 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
29590 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
295a0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
295b0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
295c0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
295d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
295e0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
295f0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
29600 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
29610 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
29620 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
29630 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
29640 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
29650 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
29660 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
29670 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
29680 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20  eeded Callbacks 
29690 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30  {H16700} <S20300
296a0 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  >.**.** To avoid
296b0 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
296c0 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
296d0 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
296e0 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
296f0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
29700 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
29710 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
29720 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
29730 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
29740 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
29750 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
29760 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
29770 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
29780 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
29790 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
297a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
297b0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
297c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
297d0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
297e0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
297f0 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
29800 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
29810 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
29820 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
29830 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
29840 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c   {H16703} If sql
29850 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
29860 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
29870 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
29880 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
29890 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
298a0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
298b0 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  r..** A call to 
298c0 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
298d0 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69  replaces any exi
298e0 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a  sting callback..
298f0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
29900 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
29910 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
29920 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
29930 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
29940 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
29950 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
29960 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
29970 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
29980 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
29990 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
299a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
299b0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
299c0 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
299d0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
299e0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
299f0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
29a00 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
29a10 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
29a20 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
29a30 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
29a40 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
29a50 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
29a60 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
29a70 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
29a80 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
29a90 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
29aa0 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
29ab0 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a   sequence..**.**
29ac0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
29ad0 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
29ae0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
29af0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
29b00 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
29b10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
29b20 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
29b30 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
29b40 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
29b50 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
29b60 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ion_v2()]..**.**
29b70 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
29b80 2a 20 5b 48 31 36 37 30 32 5d 20 5b 48 31 36 37  * [H16702] [H167
29b90 30 34 5d 20 5b 48 31 36 37 30 36 5d 0a 2a 2f 0a  04] [H16706].*/.
29ba0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
29bb0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
29bc0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
29bd0 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
29be0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
29bf0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
29c00 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
29c10 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
29c20 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
29c30 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
29c40 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
29c50 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
29c60 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
29c70 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70  d*).);../*.** Sp
29c80 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
29c90 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
29ca0 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
29cb0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
29cc0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
29cd0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
29ce0 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
29cf0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
29d00 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
29d10 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
29d20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
29d30 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
29d40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29d50 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
29d60 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
29d70 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
29d80 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
29d90 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
29da0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
29db0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
29dc0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
29dd0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
29de0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
29df0 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
29e00 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
29e10 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
29e20 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
29e30 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
29e40 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
29e50 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
29e60 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
29e70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
29e80 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
29e90 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
29ea0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
29eb0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
29ec0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
29ed0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
29ee0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
29ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29f00 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
29f10 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
29f20 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
29f30 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
29f40 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
29f50 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
29f60 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
29f70 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
29f80 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33  hort Time {H1053
29f90 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
29fa0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
29fb0 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
29fc0 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
29fd0 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
29fe0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
29ff0 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
2a000 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
2a010 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
2a020 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
2a030 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
2a040 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
2a050 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
2a060 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
2a070 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
2a080 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
2a090 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
2a0a0 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
2a0b0 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
2a0c0 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
2a0d0 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
2a0e0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
2a0f0 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
2a100 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
2a110 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2a120 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
2a130 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
2a140 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
2a150 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
2a160 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
2a170 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
2a180 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
2a190 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
2a1a0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
2a1b0 74 73 3a 20 5b 48 31 30 35 33 33 5d 20 5b 48 31  ts: [H10533] [H1
2a1c0 30 35 33 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  0536].*/.int sql
2a1d0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
2a1e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a1f0 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
2a200 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
2a210 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31  porary Files {H1
2a220 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0310} <S20000>.*
2a230 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f  *.** If this glo
2a240 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
2a250 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
2a260 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
2a270 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
2a280 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
2a290 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
2a2a0 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
2a2b0 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
2a2c0 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c  ed by SQLite wil
2a2d0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
2a2e0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20  hat directory.  
2a2f0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
2a300 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
2a310 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2a320 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
2a330 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
2a340 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
2a350 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
2a360 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
2a370 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
2a380 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
2a390 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
2a3a0 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
2a3b0 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
2a3c0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
2a3d0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
2a3e0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
2a3f0 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
2a400 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
2a410 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
2a420 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
2a430 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
2a440 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
2a450 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
2a460 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
2a470 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
2a480 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
2a490 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
2a4a0 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
2a4b0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
2a4c0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
2a4d0 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
2a4e0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
2a4f0 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
2a500 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
2a510 2a 2a 0a 2a 2a 20 54 68 65 20 5b 74 65 6d 70 5f  **.** The [temp_
2a520 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
2a530 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
2a540 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
2a550 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
2a560 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
2a570 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2a580 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2a590 63 5d 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  c].  Furthermore
2a5a0 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
2a5b0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
2a5c0 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
2a5d0 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
2a5e0 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
2a5f0 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
2a600 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
2a610 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2a620 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
2a630 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
2a640 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
2a650 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
2a660 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
2a670 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
2a680 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
2a690 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
2a6a0 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
2a6b0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
2a6c0 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
2a6d0 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
2a6e0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2a6f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2a700 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
2a710 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
2a720 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
2a730 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
2a740 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
2a750 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
2a760 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
2a770 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
2a780 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
2a790 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
2a7a0 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
2a7b0 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36  ode {H12930} <S6
2a7c0 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
2a7d0 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
2a7e0 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ode}.**.** The s
2a7f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
2a800 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
2a810 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
2a820 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
2a830 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
2a840 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2a850 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
2a860 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
2a870 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2a880 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
2a890 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
2a8a0 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69  lt..** Autocommi
2a8b0 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
2a8c0 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
2a8d0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75  statement..** Au
2a8e0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2a8f0 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
2a900 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
2a910 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
2a920 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
2a930 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
2a940 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
2a950 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
2a960 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
2a970 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
2a980 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
2a990 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
2a9a0 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
2a9b0 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
2a9c0 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
2a9d0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
2a9e0 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
2a9f0 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
2aa00 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
2aa10 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
2aa20 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
2aa30 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
2aa40 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
2aa50 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
2aa60 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2aa70 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
2aa80 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
2aa90 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
2aaa0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
2aab0 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
2aac0 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
2aad0 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
2aae0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2aaf0 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
2ab00 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
2ab10 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
2ab20 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
2ab30 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  defined..**.** R
2ab40 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
2ab50 32 39 33 31 5d 20 5b 48 31 32 39 33 32 5d 20 5b  2931] [H12932] [
2ab60 48 31 32 39 33 33 5d 20 5b 48 31 32 39 33 34 5d  H12933] [H12934]
2ab70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ab80 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
2ab90 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
2aba0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
2abb0 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
2abc0 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
2abd0 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d Statement {H13
2abe0 31 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a  120} <S60600>.**
2abf0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ac00 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
2ac10 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2ac20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ac30 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
2ac40 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
2ac50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ac60 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b 64  belongs.  The [d
2ac70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ac80 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
2ac90 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
2aca0 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
2acb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2acc0 63 74 69 6f 6e 5d 20 74 68 61 74 20 77 61 73 20  ction] that was 
2acd0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2ace0 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
2acf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ad00 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
2ad10 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
2ad20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
2ad30 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
2ad40 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
2ad50 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65   place..**.** Re
2ad60 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33  quirements: [H13
2ad70 31 32 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  123].*/.sqlite3 
2ad80 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
2ad90 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2ada0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2adb0 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
2adc0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2add0 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53  ment {H13140} <S
2ade0 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  60600>.**.** Thi
2adf0 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
2ae00 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2ae10 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
2ae20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2ae30 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
2ae40 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2ae50 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2ae60 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66  ection] pDb.  If
2ae70 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
2ae80 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
2ae90 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2aea0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2aeb0 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
2aec0 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
2aed0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
2aee0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2aef0 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70  on pDb.  If no p
2af00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2af10 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
2af20 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
2af30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
2af40 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
2af50 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
2af60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2af70 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
2af80 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2af90 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
2afa0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
2afb0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2afc0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2afd0 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
2afe0 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
2aff0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2b000 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
2b010 3a 20 5b 48 31 33 31 34 33 5d 20 5b 48 31 33 31  : [H13143] [H131
2b020 34 36 5d 20 5b 48 31 33 31 34 39 5d 20 5b 48 31  46] [H13149] [H1
2b030 33 31 35 32 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  3152].*/.sqlite3
2b040 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
2b050 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
2b060 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
2b070 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2b080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2b090 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
2b0a0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
2b0b0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30  allbacks {H12950
2b0c0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
2b0d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d   The sqlite3_com
2b0e0 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
2b0f0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2b100 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
2b110 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
2b120 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
2b130 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43  ransaction is [C
2b140 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65  OMMIT | committe
2b150 64 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  d]..** Any callb
2b160 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2b170 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
2b180 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2b190 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
2b1a0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2b1b0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2b1c0 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71  idden..** The sq
2b1d0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2b1e0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2b1f0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2b200 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2b210 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2b220 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2b230 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41  ction is [ROLLBA
2b240 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b  CK | rolled back
2b250 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61  ]..** Any callba
2b260 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
2b270 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
2b280 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2b290 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
2b2a0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2b2b0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2b2c0 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72  dden..** The pAr
2b2d0 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
2b2e0 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
2b2f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2b300 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
2b310 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
2b320 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  k function retur
2b330 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20  ns non-zero,.** 
2b340 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
2b350 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
2b360 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
2b370 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66  .** If another f
2b380 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76  unction was prev
2b390 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
2b3a0 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76  d, its.** pArg v
2b3b0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2b3c0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  .  Otherwise NUL
2b3d0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
2b3e0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2b3f0 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2b400 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2b410 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2b420 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2b430 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b440 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2b450 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
2b460 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2b470 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2b480 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2b490 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2b4a0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2b4b0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2b4c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2b4d0 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2b4e0 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
2b4f0 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
2b500 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
2b510 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
2b520 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2b530 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b540 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2b550 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2b560 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2b570 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2b580 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2b590 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2b5a0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2b5b0 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67  *.** Registering
2b5c0 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
2b5d0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
2b5e0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68  llback..**.** Wh
2b5f0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
2b600 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  ok callback rout
2b610 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
2b620 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a  , the [COMMIT].*
2b630 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  * operation is a
2b640 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e  llowed to contin
2b650 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 49 66  ue normally.  If
2b660 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
2b670 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
2b680 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
2b690 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
2b6a0 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
2b6b0 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 54 68 65 20 72  LBACK]..** The r
2b6c0 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
2b6d0 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
2b6e0 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
2b6f0 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
2b700 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
2b710 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
2b720 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
2b730 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
2b740 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2b750 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
2b760 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
2b770 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
2b780 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
2b790 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
2b7a0 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
2b7b0 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
2b7c0 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
2b7d0 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
2b7e0 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
2b7f0 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
2b800 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
2b810 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ur..** The rollb
2b820 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
2b830 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
2b840 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
2b850 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
2b860 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
2b870 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
2b880 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2b890 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72  closed..** The r
2b8a0 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
2b8b0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2b8c0 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
2b8d0 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61   is.** rolled ba
2b8e0 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d  ck because a com
2b8f0 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
2b900 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a  urned non-zero..
2b910 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20  ** <todo> Check 
2b920 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a  on this </todo>.
2b930 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2b940 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
2b950 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
2b960 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  face..**.** Requ
2b970 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
2b980 32 39 35 31 5d 20 5b 48 31 32 39 35 32 5d 20 5b  2951] [H12952] [
2b990 48 31 32 39 35 33 5d 20 5b 48 31 32 39 35 34 5d  H12953] [H12954]
2b9a0 20 5b 48 31 32 39 35 35 5d 0a 2a 2a 20 5b 48 31   [H12955].** [H1
2b9b0 32 39 36 31 5d 20 5b 48 31 32 39 36 32 5d 20 5b  2961] [H12962] [
2b9c0 48 31 32 39 36 33 5d 20 5b 48 31 32 39 36 34 5d  H12963] [H12964]
2b9d0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2b9e0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
2b9f0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
2ba00 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
2ba10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
2ba20 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
2ba30 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
2ba40 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
2ba50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2ba60 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
2ba70 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
2ba80 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 34  s {H12970} <S604
2ba90 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2baa0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2bab0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
2bac0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
2bad0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
2bae0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2baf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
2bb00 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
2bb10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2bb20 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
2bb30 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
2bb40 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2bb50 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2bb60 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
2bb70 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2bb80 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
2bb90 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
2bba0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2bbb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2bbc0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
2bbd0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2bbe0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2bbf0 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
2bc00 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
2bc10 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
2bc20 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2bc30 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68  r deleted..** Th
2bc40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2bc50 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2bc60 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
2bc70 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2bc80 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  .** to sqlite3_u
2bc90 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a  pdate_hook()..**
2bca0 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c   The second call
2bcb0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
2bcc0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2bcd0 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
2bce0 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20  _DELETE],.** or 
2bcf0 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
2bd00 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
2bd10 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
2bd20 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
2bd30 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  back.** to be in
2bd40 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68  voked..** The th
2bd50 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
2bd60 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2bd70 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
2bd80 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
2bd90 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
2bda0 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
2bdb0 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
2bdc0 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20  ted row..** The 
2bdd0 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
2bde0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2bdf0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72  [rowid] of the r
2be00 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61  ow..** In the ca
2be10 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
2be20 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f   this is the [ro
2be30 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75  wid] after the u
2be40 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63  pdate takes plac
2be50 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
2be60 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20  ate hook is not 
2be70 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
2be80 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62  ernal system tab
2be90 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66  les are.** modif
2bea0 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65  ied (i.e. sqlite
2beb0 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
2bec0 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a  te_sequence)..**
2bed0 0a 2a 2a 20 49 6e 20 74 68 65 20 63 75 72 72 65  .** In the curre
2bee0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
2bef0 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
2bf00 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
2bf10 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
2bf20 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
2bf30 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
2bf40 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
2bf50 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
2bf60 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
2bf70 73 65 2e 20 20 4e 6f 72 20 69 73 20 74 68 65 20  se.  Nor is the 
2bf80 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
2bf90 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
2bfa0 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
2bfb0 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
2bfc0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
2bfd0 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
2bfe0 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
2bff0 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
2c000 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
2c010 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
2c020 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2c030 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
2c040 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2c050 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2c060 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2c070 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2c080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c090 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2c0a0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
2c0b0 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
2c0c0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
2c0d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c0e0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
2c0f0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
2c100 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
2c110 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2c120 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
2c130 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
2c140 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
2c150 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2c160 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c170 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2c180 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2c190 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2c1a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2c1b0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2c1c0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2c1d0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2c1e0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
2c1f0 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
2c200 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
2c210 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c  ed, its pArg val
2c220 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ue.** is returne
2c230 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
2c240 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
2c250 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2c260 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
2c270 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b  it_hook()] and [
2c280 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
2c290 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65  _hook()].** inte
2c2a0 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65  rfaces..**.** Re
2c2b0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
2c2c0 48 31 32 39 37 31 5d 20 5b 48 31 32 39 37 33 5d  H12971] [H12973]
2c2d0 20 5b 48 31 32 39 37 35 5d 20 5b 48 31 32 39 37   [H12975] [H1297
2c2e0 37 5d 20 5b 48 31 32 39 37 39 5d 20 5b 48 31 32  7] [H12979] [H12
2c2f0 39 38 31 5d 20 5b 48 31 32 39 38 33 5d 20 5b 48  981] [H12983] [H
2c300 31 32 39 38 36 5d 0a 2a 2f 0a 76 6f 69 64 20 2a  12986].*/.void *
2c310 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2c320 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ook(.  sqlite3*,
2c330 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
2c340 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e   *,int ,char con
2c350 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20  st *,char const 
2c360 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
2c370 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a  ,.  void*.);../*
2c380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
2c390 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
2c3a0 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
2c3b0 68 65 20 7b 48 31 30 33 33 30 7d 20 3c 53 33 30  he {H10330} <S30
2c3c0 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  900>.** KEYWORDS
2c3d0 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d  : {shared cache}
2c3e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2c3f0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
2c400 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
2c410 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
2c420 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
2c430 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
2c440 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
2c450 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2c460 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f  tion | connectio
2c470 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  ns].** to the sa
2c480 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61  me database. Sha
2c490 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2c4a0 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
2c4b0 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64  is true.** and d
2c4c0 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
2c4d0 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65  rgument is false
2c4e0 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68  ..**.** Cache sh
2c4f0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
2c500 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f   and disabled fo
2c510 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
2c520 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ess..** This is 
2c530 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
2c540 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
2c550 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
2c560 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2c570 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
2c580 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2c590 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
2c5a0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
2c5b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65  .**.** The cache
2c5c0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
2c5d0 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
2c5e0 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
2c5f0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
2c600 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2c610 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2c620 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
2c630 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
2c640 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
2c650 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
2c660 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
2c670 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
2c680 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
2c690 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
2c6a0 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
2c6b0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56   opened..**.** V
2c6c0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
2c6d0 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74  nnot be used wit
2c6e0 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65  h a shared cache
2c6f0 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a  .  When shared.*
2c700 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
2c710 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ed, the [sqlite3
2c720 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
2c730 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65  ] API used to re
2c740 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61  gister.** virtua
2c750 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c  l tables will al
2c760 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65  ways return an e
2c770 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rror..**.** This
2c780 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2c790 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
2c7a0 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
2c7b0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2c7c0 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66  bled.** successf
2c7d0 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72  ully.  An [error
2c7e0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2c7f0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
2c800 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65  .** Shared cache
2c810 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
2c820 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
2c830 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
2c840 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
2c850 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
2c860 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
2c870 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
2c880 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
2c890 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
2c8a0 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
2c8b0 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20  **.** See Also: 
2c8c0 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d   [SQLite Shared-
2c8d0 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a 2a  Cache Mode].**.*
2c8e0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
2c8f0 5b 48 31 30 33 33 31 5d 20 5b 48 31 30 33 33 36  [H10331] [H10336
2c900 5d 20 5b 48 31 30 33 33 37 5d 20 5b 48 31 30 33  ] [H10337] [H103
2c910 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  39].*/.int sqlit
2c920 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
2c930 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
2c940 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74  .** CAPI3REF: At
2c950 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
2c960 61 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34  ap Memory {H1734
2c970 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a  0} <S30220>.**.*
2c980 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2c990 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
2c9a0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2c9b0 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
2c9c0 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
2c9d0 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
2c9e0 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
2c9f0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
2ca00 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
2ca10 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
2ca20 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d  rary. {END}  Mem
2ca30 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68  ory used to cach
2ca40 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61  e database.** pa
2ca50 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70  ges to improve p
2ca60 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e  erformance is an
2ca70 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d   example of non-
2ca80 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
2ca90 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c  ..** sqlite3_rel
2caa0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65  ease_memory() re
2cab0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2cac0 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c   of bytes actual
2cad0 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69  ly freed,.** whi
2cae0 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65  ch might be more
2caf0 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68   or less than th
2cb00 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74  e amount request
2cb10 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ed..**.** Requir
2cb20 65 6d 65 6e 74 73 3a 20 5b 48 31 37 33 34 31 5d  ements: [H17341]
2cb30 20 5b 48 31 37 33 34 32 5d 0a 2a 2f 0a 69 6e 74   [H17342].*/.int
2cb40 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2cb50 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
2cb60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2cb70 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
2cb80 20 48 65 61 70 20 53 69 7a 65 20 7b 48 31 37 33   Heap Size {H173
2cb90 35 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a  50} <S30220>.**.
2cba0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
2cbb0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29  oft_heap_limit()
2cbc0 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65   interface place
2cbd0 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  s a "soft" limit
2cbe0 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e  .** on the amoun
2cbf0 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  t of heap memory
2cc00 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c   that may be all
2cc10 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
2cc20 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  ..** If an inter
2cc30 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  nal allocation i
2cc40 73 20 72 65 71 75 65 73 74 65 64 20 74 68 61 74  s requested that
2cc50 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2cc60 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c  e.** soft heap l
2cc70 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72  imit, [sqlite3_r
2cc80 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
2cc90 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20   is invoked one 
2cca0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73  or.** more times
2ccb0 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65   to free up some
2ccc0 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68   space before th
2ccd0 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  e allocation is 
2cce0 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a  performed..**.**
2ccf0 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61   The limit is ca
2cd00 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63  lled "soft", bec
2cd10 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33  ause if [sqlite3
2cd20 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2cd30 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65  )].** cannot fre
2cd40 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  e sufficient mem
2cd50 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74  ory to prevent t
2cd60 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65  he limit from be
2cd70 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a  ing exceeded,.**
2cd80 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61   the memory is a
2cd90 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20  llocated anyway 
2cda0 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  and the current 
2cdb0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
2cdc0 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61  ds..**.** A nega
2cdd0 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c  tive or zero val
2cde0 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74  ue for N means t
2cdf0 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hat there is no 
2ce00 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2ce10 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2ce20 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2ce30 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63  ] will only be c
2ce40 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72  alled when memor
2ce50 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a  y is exhausted..
2ce60 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  ** The default v
2ce70 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66  alue for the sof
2ce80 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
2ce90 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  zero..**.** SQLi
2cea0 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20  te makes a best 
2ceb0 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20  effort to honor 
2cec0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2ced0 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74  mit..** But if t
2cee0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2cef0 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e  it cannot be hon
2cf00 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20  ored, execution 
2cf10 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65  will.** continue
2cf20 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f   without error o
2cf30 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20  r notification. 
2cf40 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65   This is why the
2cf50 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c   limit is.** cal
2cf60 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d  led a "soft" lim
2cf70 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73  it.  It is advis
2cf80 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ory only..**.** 
2cf90 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
2cfa0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74  version 3.5.0, t
2cfb0 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
2cfc0 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65   constrained the
2cfd0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
2cfe0 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  ated by a single
2cff0 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61   thread - the sa
2d000 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2d010 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  ch this routine.
2d020 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e  ** runs.  Beginn
2d030 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20  ing with SQLite 
2d040 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74  version 3.5.0, t
2d050 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2d060 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64  it is.** applied
2d070 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e   to all threads.
2d080 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69   The value speci
2d090 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66  fied for the sof
2d0a0 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20  t heap limit.** 
2d0b0 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e  is an upper boun
2d0c0 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d  d on the total m
2d0d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2d0e0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73   for all threads
2d0f0 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  . In.** version 
2d100 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e  3.5.0 there is n
2d110 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20  o mechanism for 
2d120 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61  limiting the hea
2d130 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69  p usage for.** i
2d140 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64  ndividual thread
2d150 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  s..**.** Require
2d160 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 33 35  ments:.** [H1635
2d170 31 5d 20 5b 48 31 36 33 35 32 5d 20 5b 48 31 36  1] [H16352] [H16
2d180 33 35 33 5d 20 5b 48 31 36 33 35 34 5d 20 5b 48  353] [H16354] [H
2d190 31 36 33 35 35 5d 20 5b 48 31 36 33 35 38 5d 0a  16355] [H16358].
2d1a0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2d1b0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
2d1c0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2d1d0 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d  I3REF: Extract M
2d1e0 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
2d1f0 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
2d200 65 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 33  e {H12850} <S603
2d210 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
2d220 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d  outine returns m
2d230 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20  etadata about a 
2d240 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
2d250 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  of a specific.**
2d260 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
2d270 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
2d280 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2d290 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
2d2a0 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  e.** passed as t
2d2b0 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
2d2c0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2d2d0 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  * The column is 
2d2e0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
2d2f0 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
2d300 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
2d310 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73  eters to.** this
2d320 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73   function. The s
2d330 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2d340 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
2d350 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2d360 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
2d370 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e  n", "temp" or an
2d380 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2d390 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  se) containing t
2d3a0 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  he specified.** 
2d3b0 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49  table or NULL. I
2d3c0 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
2d3d0 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
2d3e0 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
2d3f0 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
2d400 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
2d410 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
2d420 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74   used by the dat
2d430 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a  abase engine to.
2d440 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
2d450 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
2d460 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  erences..**.** T
2d470 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
2d480 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
2d490 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
2d4a0 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
2d4b0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65  d column.** name
2d4c0 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
2d4d0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
2d4e0 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
2d4f0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
2d500 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  s.** may be NULL
2d510 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74 61  ..**.** Metadata
2d520 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
2d530 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
2d540 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
2d550 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74  passed as the 5t
2d560 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75  h.** and subsequ
2d570 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
2d580 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
2d590 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72   Any of these ar
2d5a0 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a  guments may be.*
2d5b0 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68  * NULL, in which
2d5c0 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73   case the corres
2d5d0 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20  ponding element 
2d5e0 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f  of metadata is o
2d5f0 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  mitted..**.** <b
2d600 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
2d610 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
2d620 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72  .** <tr><th> Par
2d630 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70  ameter <th> Outp
2d640 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ut<br>Type <th> 
2d650 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a   Description.**.
2d660 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20  ** <tr><td> 5th 
2d670 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
2d680 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a   <td> Data type.
2d690 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20  ** <tr><td> 6th 
2d6a0 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
2d6b0 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65   <td> Name of de
2d6c0 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
2d6d0 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e  sequence.** <tr>
2d6e0 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e  <td> 7th <td> in
2d6f0 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
2d700 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61  rue if column ha
2d710 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
2d720 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c  straint.** <tr><
2d730 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74  td> 8th <td> int
2d740 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
2d750 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
2d760 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
2d770 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c  ARY KEY.** <tr><
2d780 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74  td> 9th <td> int
2d790 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
2d7a0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
2d7b0 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a  [AUTOINCREMENT].
2d7c0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2d7d0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2d7e0 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f  ** The memory po
2d7f0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
2d800 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65  character pointe
2d810 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20  rs returned for 
2d820 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69  the.** declarati
2d830 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c  on type and coll
2d840 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
2d850 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74  s valid only unt
2d860 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63  il the next.** c
2d870 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74  all to any SQLit
2d880 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a  e API function..
2d890 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65  **.** If the spe
2d8a0 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
2d8b0 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
2d8c0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2d8d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2d8e0 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69  .** If the speci
2d8f0 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22  fied column is "
2d900 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72  rowid", "oid" or
2d910 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61   "_rowid_" and a
2d920 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52  n.** [INTEGER PR
2d930 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d  IMARY KEY] colum
2d940 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
2d950 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
2d960 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a  then the output.
2d970 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
2d980 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78  e set for the ex
2d990 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
2d9a0 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65  d column. If the
2d9b0 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
2d9c0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
2d9d0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2d9e0 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68   KEY] column, th
2d9f0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
2da00 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2da10 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  set as follows:.
2da20 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
2da30 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
2da40 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
2da50 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2da60 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
2da70 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
2da80 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
2da90 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
2daa0 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
2dab0 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68   </pre>.**.** Th
2dac0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
2dad0 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
2dae0 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
2daf0 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
2db00 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
2db10 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
2db20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
2db30 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
2db40 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
2db50 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
2db60 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2db70 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
2db80 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
2db90 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65  e left.** in the
2dba0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2dbb0 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65  ction] (to be re
2dbc0 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
2dbd0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
2dbe0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
2dbf0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
2dc00 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
2dc10 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
2dc20 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
2dc30 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
2dc40 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
2dc50 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
2dc60 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
2dc70 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f  sqlite3_table_co
2dc80 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20  lumn_metadata(. 
2dc90 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2dca0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2dcb0 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c  Connection handl
2dcc0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2dcd0 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
2dce0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e     /* Database n
2dcf0 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20  ame or NULL */. 
2dd00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
2dd10 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20  bleName,     /* 
2dd20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  Table name */.  
2dd30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
2dd40 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43  umnName,    /* C
2dd50 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20  olumn name */.  
2dd60 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44  char const **pzD
2dd70 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f  ataType,    /* O
2dd80 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20  UTPUT: Declared 
2dd90 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63  data type */.  c
2dda0 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f  har const **pzCo
2ddb0 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55  llSeq,     /* OU
2ddc0 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  TPUT: Collation 
2ddd0 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f  sequence name */
2dde0 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c  .  int *pNotNull
2ddf0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2de00 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2de10 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  f NOT NULL const
2de20 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a  raint exists */.
2de30 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b    int *pPrimaryK
2de40 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ey,           /*
2de50 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
2de60 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20   column part of 
2de70 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75  PK */.  int *pAu
2de80 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20  toinc           
2de90 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
2dea0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
2deb0 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20   auto-increment 
2dec0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
2ded0 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45  I3REF: Load An E
2dee0 78 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 30 30  xtension {H12600
2def0 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20500>.**.**
2df00 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2df10 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20  loads an SQLite 
2df20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
2df30 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64  y from the named
2df40 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   file..**.** {H1
2df50 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65  2601} The sqlite
2df60 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
2df70 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
2df80 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e  empts to load an
2df90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
2dfa0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
2dfb0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
2dfc0 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c  in the file zFil
2dfd0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 32  e..**.** {H12602
2dfe0 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  } The entry poin
2dff0 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a 2a  t is zProc..**.*
2e000 2a 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 6f 63  * {H12603} zProc
2e010 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68   may be 0, in wh
2e020 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d  ich case the nam
2e030 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
2e040 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  oint.**         
2e050 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71   defaults to "sq
2e060 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f  lite3_extension_
2e070 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  init"..**.** {H1
2e080 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74 65  2604} The sqlite
2e090 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
2e0a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  () interface sha
2e0b0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  ll return.**    
2e0c0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b        [SQLITE_OK
2e0d0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
2e0e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2e0f0 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65  if something goe
2e100 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  s wrong..**.** {
2e110 48 31 32 36 30 35 7d 20 49 66 20 61 6e 20 65 72  H12605} If an er
2e120 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70  ror occurs and p
2e130 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30  zErrMsg is not 0
2e140 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20  , then the.**   
2e150 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2e160 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2e170 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
2e180 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20  l attempt to.** 
2e190 20 20 20 20 20 20 20 20 20 66 69 6c 6c 20 2a 70           fill *p
2e1a0 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72  zErrMsg with err
2e1b0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
2e1c0 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79  stored in memory
2e1d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74  .**          obt
2e1e0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2e1f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 7b  te3_malloc()]. {
2e200 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e  END}  The callin
2e210 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  g function.**   
2e220 20 20 20 20 20 20 20 73 68 6f 75 6c 64 20 66 72         should fr
2e230 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62  ee this memory b
2e240 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2e250 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2e260 2a 20 7b 48 31 32 36 30 36 7d 20 45 78 74 65 6e  * {H12606} Exten
2e270 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
2e280 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
2e290 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
2e2a0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
2e2b0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
2e2c0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
2e2d0 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 20  g this API,.**  
2e2e0 20 20 20 20 20 20 20 20 6f 74 68 65 72 77 69 73          otherwis
2e2f0 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  e an error will 
2e300 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  be returned..*/.
2e310 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
2e320 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
2e330 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2e340 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
2e350 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
2e360 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
2e370 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
2e380 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
2e390 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
2e3a0 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
2e3b0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
2e3c0 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
2e3d0 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
2e3e0 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
2e3f0 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
2e400 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
2e410 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
2e420 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
2e430 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
2e440 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
2e450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
2e460 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
2e470 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
2e480 6e 67 20 7b 48 31 32 36 32 30 7d 20 3c 53 32 30  ng {H12620} <S20
2e490 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73  500>.**.** So as
2e4a0 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
2e4b0 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
2e4c0 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
2e4d0 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
2e4e0 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
2e4f0 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
2e500 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
2e510 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
2e520 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
2e530 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
2e540 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
2e550 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
2e560 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a   following API.*
2e570 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  * is provided to
2e580 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
2e590 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2e5a0 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
2e5b0 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a  n and off..**.**
2e5c0 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   Extension loadi
2e5d0 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  ng is off by def
2e5e0 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74  ault. See ticket
2e5f0 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 48   #1863..**.** {H
2e600 31 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20  12621} Call the 
2e610 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
2e620 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2e630 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f  routine with ono
2e640 66 66 3d 3d 31 0a 2a 2a 20 20 20 20 20 20 20 20  ff==1.**        
2e650 20 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73    to turn extens
2e660 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61  ion loading on a
2e670 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
2e680 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
2e690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20  .**          it 
2e6a0 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a  back off again..
2e6b0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 32 7d 20 45  **.** {H12622} E
2e6c0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
2e6d0 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75   is off by defau
2e6e0 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  lt..*/.int sqlit
2e6f0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
2e700 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33  xtension(sqlite3
2e710 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29   *db, int onoff)
2e720 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e730 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79  F: Automatically
2e740 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
2e750 6f 6e 73 20 7b 48 31 32 36 34 30 7d 20 3c 53 32  ons {H12640} <S2
2e760 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0500>.**.** This
2e770 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
2e780 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
2e790 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
2e7a0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
2e7b0 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
2e7c0 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
2e7d0 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
2e7e0 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
2e7f0 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61  * to all new [da
2e800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e810 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ns]. {END}.**.**
2e820 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   This routine st
2e830 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ores a pointer t
2e840 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  o the extension 
2e850 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74  in an array that
2e860 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20   is.** obtained 
2e870 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2e880 6c 6c 6f 63 28 29 5d 2e 20 20 49 66 20 79 6f 75  lloc()].  If you
2e890 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65   run a memory le
2e8a0 61 6b 20 63 68 65 63 6b 65 72 0a 2a 2a 20 6f 6e  ak checker.** on
2e8b0 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e   your program an
2e8c0 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c  d it reports a l
2e8d0 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74  eak because of t
2e8e0 68 69 73 20 61 72 72 61 79 2c 20 69 6e 76 6f 6b  his array, invok
2e8f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  e.** [sqlite3_re
2e900 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
2e910 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 73  on()] prior to s
2e920 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65 20  hutdown to free 
2e930 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a  the memory..**.*
2e940 2a 20 7b 48 31 32 36 34 31 7d 20 54 68 69 73 20  * {H12641} This 
2e950 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
2e960 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20  rs an extension 
2e970 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74  entry point that
2e980 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2e990 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2e9a0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2e9b0 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
2e9c0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20  onnection].**   
2e9d0 20 20 20 20 20 20 20 69 73 20 6f 70 65 6e 65 64         is opened
2e9e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2e9f0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2ea00 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20  3_open16()],.** 
2ea10 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2ea20 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
2ea30 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 7d 20  .**.** {H12642} 
2ea40 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73  Duplicate extens
2ea50 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65  ions are detecte
2ea60 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  d so calling thi
2ea70 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20  s routine.**    
2ea80 20 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 20 74        multiple t
2ea90 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
2eaa0 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20  me extension is 
2eab0 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  harmless..**.** 
2eac0 7b 48 31 32 36 34 33 7d 20 54 68 69 73 20 72 6f  {H12643} This ro
2ead0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70  utine stores a p
2eae0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78  ointer to the ex
2eaf0 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72  tension in an ar
2eb00 72 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ray.**          
2eb10 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64  that is obtained
2eb20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2eb30 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alloc()]..**.** 
2eb40 7b 48 31 32 36 34 34 7d 20 41 75 74 6f 6d 61 74  {H12644} Automat
2eb50 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70  ic extensions ap
2eb60 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74  ply across all t
2eb70 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73  hreads..*/.int s
2eb80 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65  qlite3_auto_exte
2eb90 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e  nsion(void (*xEn
2eba0 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29  tryPoint)(void))
2ebb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ebc0 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74  F: Reset Automat
2ebd0 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  ic Extension Loa
2ebe0 64 69 6e 67 20 7b 48 31 32 36 36 30 7d 20 3c 53  ding {H12660} <S
2ebf0 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20500>.**.** Thi
2ec00 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  s function disab
2ec10 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73  les all previous
2ec20 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75  ly registered au
2ec30 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e  tomatic.** exten
2ec40 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49 74  sions. {END}  It
2ec50 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
2ec60 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a  ct of all prior.
2ec70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f  ** [sqlite3_auto
2ec80 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61  _extension()] ca
2ec90 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36  lls..**.** {H126
2eca0 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f  61} This functio
2ecb0 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70  n disables all p
2ecc0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
2ecd0 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
2ece0 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   automatic exten
2ecf0 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  sions..**.** {H1
2ed00 32 36 36 32 7d 20 54 68 69 73 20 66 75 6e 63 74  2662} This funct
2ed10 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74  ion disables aut
2ed20 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
2ed30 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73  s in all threads
2ed40 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2ed50 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74  3_reset_auto_ext
2ed60 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f  ension(void);../
2ed70 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d  *.****** EXPERIM
2ed80 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20  ENTAL - subject 
2ed90 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
2eda0 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a  t notice *******
2edb0 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  *******.**.** Th
2edc0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
2edd0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
2ede0 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75   mechanism is cu
2edf0 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
2ee00 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
2ee10 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
2ee20 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
2ee30 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
2ee40 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
2ee50 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
2ee60 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
2ee70 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
2ee80 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
2ee90 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
2eea0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
2eeb0 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69   mechanism stabi
2eec0 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
2eed0 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
2eee0 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
2eef0 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
2ef00 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
2ef10 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
2ef20 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63  .*/../*.** Struc
2ef30 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68  tures used by th
2ef40 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
2ef50 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70  interface.*/.typ
2ef60 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2ef70 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33  te3_vtab sqlite3
2ef80 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73  _vtab;.typedef s
2ef90 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
2efa0 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33  dex_info sqlite3
2efb0 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70  _index_info;.typ
2efc0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2efd0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
2efe0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2eff0 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72  sor;.typedef str
2f000 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
2f010 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  le sqlite3_modul
2f020 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
2f030 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
2f040 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 30 30  e Object {H18000
2f050 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45  } <S20400>.** KE
2f060 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
2f070 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20  module {virtual 
2f080 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a  table module}.**
2f090 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
2f0a0 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
2f0b0 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61  re, sometimes ca
2f0c0 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61  lled a a "virtua
2f0d0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c  l table module",
2f0e0 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65   .** defines the
2f0f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f100 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  of a [virtual ta
2f110 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73  bles].  .** This
2f120 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69   structure consi
2f130 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65  sts mostly of me
2f140 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
2f150 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 69  dule..**.** A vi
2f160 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
2f170 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79  le is created by
2f180 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65   filling in a pe
2f190 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74  rsistent.** inst
2f1a0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
2f1b0 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69  ucture and passi
2f1c0 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ng a pointer to 
2f1d0 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  that instance.**
2f1e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2f1f0 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72  ate_module()] or
2f200 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f210 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a  _module_v2()]..*
2f220 2a 20 54 68 65 20 72 65 67 69 73 74 72 61 74 69  * The registrati
2f230 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64  on remains valid
2f240 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70   until it is rep
2f250 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65  laced by a diffe
2f260 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f  rent.** module o
2f270 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74  r until the [dat
2f280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f290 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63  ] closes.  The c
2f2a0 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69  ontent.** of thi
2f2b0 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74  s structure must
2f2c0 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c   not change whil
2f2d0 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72  e it is register
2f2e0 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64  ed with.** any d
2f2f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f300 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  on..*/.struct sq
2f310 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20  lite3_module {. 
2f320 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
2f330 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28   int (*xCreate)(
2f340 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
2f350 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
2f360 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
2f370 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
2f380 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
2f390 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
2f3a0 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
2f3b0 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  r**);.  int (*xC
2f3c0 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a  onnect)(sqlite3*
2f3d0 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
2f3e0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
2f3f0 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
2f400 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
2f410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
2f420 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
2f430 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
2f440 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78  int (*xBestIndex
2f450 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2f460 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69  pVTab, sqlite3_i
2f470 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69  ndex_info*);.  i
2f480 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74  nt (*xDisconnect
2f490 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2f4a0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
2f4b0 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65  xDestroy)(sqlite
2f4c0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
2f4d0 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
2f4e0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2f4f0 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62  ab, sqlite3_vtab
2f500 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73  _cursor **ppCurs
2f510 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  or);.  int (*xCl
2f520 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ose)(sqlite3_vta
2f530 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
2f540 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c  t (*xFilter)(sql
2f550 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2f560 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63  *, int idxNum, c
2f570 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74  onst char *idxSt
2f580 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  r,.             
2f590 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c     int argc, sql
2f5a0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67  ite3_value **arg
2f5b0 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78  v);.  int (*xNex
2f5c0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  t)(sqlite3_vtab_
2f5d0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
2f5e0 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f  (*xEof)(sqlite3_
2f5f0 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
2f600 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28   int (*xColumn)(
2f610 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2f620 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f  sor*, sqlite3_co
2f630 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20  ntext*, int);.  
2f640 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71  int (*xRowid)(sq
2f650 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2f660 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
2f670 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e  4 *pRowid);.  in
2f680 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c  t (*xUpdate)(sql
2f690 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74  ite3_vtab *, int
2f6a0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
2f6b0 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  **, sqlite3_int6
2f6c0 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  4 *);.  int (*xB
2f6d0 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  egin)(sqlite3_vt
2f6e0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
2f6f0 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
2f700 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
2f710 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74  .  int (*xCommit
2f720 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2f730 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
2f740 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74  xRollback)(sqlit
2f750 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
2f760 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75  .  int (*xFindFu
2f770 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f  nction)(sqlite3_
2f780 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74  vtab *pVtab, int
2f790 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61   nArg, const cha
2f7a0 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20  r *zName,.      
2f7b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f7c0 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29   void (**pxFunc)
2f7d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2f7e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2f7f0 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20  lue**),.        
2f800 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2f810 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20  oid **ppArg);.  
2f820 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73  int (*xRename)(s
2f830 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
2f840 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ab, const char *
2f850 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  zNew);.};../*.**
2f860 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
2f870 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e  al Table Indexin
2f880 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48  g Information {H
2f890 31 38 31 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18100} <S20400>.
2f8a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
2f8b0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
2f8c0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
2f8d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2f8e0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
2f8f0 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
2f900 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
2f910 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20  used to.** pass 
2f920 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f  information into
2f930 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65   and receive the
2f940 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20   reply from the 
2f950 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20  [xBestIndex].** 
2f960 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72  method of a [vir
2f970 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
2f980 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  e].  The fields 
2f990 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
2f9a0 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
2f9b0 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
2f9c0 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
2f9d0 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
2f9e0 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
2f9f0 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
2fa00 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
2fa10 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43  ds..**.** The aC
2fa20 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
2fa30 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
2fa40 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
2fa50 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a  ts of the form:.
2fa60 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d  **.** <pre>colum
2fa70 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a  n OP expr</pre>.
2fa80 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69  **.** where OP i
2fa90 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d  s =, &lt;, &lt;=
2faa0 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d  , &gt;, or &gt;=
2fab0 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 6c 61  .  The particula
2fac0 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
2fad0 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
2fae0 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68  traint[].op.  Th
2faf0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2fb00 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20  olumn is stored 
2fb10 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e  in.** aConstrain
2fb20 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43  t[].iColumn.  aC
2fb30 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62  onstraint[].usab
2fb40 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68  le is TRUE if th
2fb50 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65  e.** expr on the
2fb60 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
2fb70 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65   can be evaluate
2fb80 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20  d (and thus the 
2fb90 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73  constraint.** is
2fba0 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c   usable) and fal
2fbb0 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e  se if it cannot.
2fbc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d  .**.** The optim
2fbd0 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
2fbe0 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
2fbf0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
2fc00 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
2fc10 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
2fc20 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
2fc30 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
2fc40 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
2fc50 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
2fc60 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
2fc70 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
2fc80 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
2fc90 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
2fca0 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  * The aConstrain
2fcb0 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
2fcc0 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
2fcd0 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65  use terms in the
2fce0 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d   correct.** form
2fcf0 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74   that refer to t
2fd00 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69  he particular vi
2fd10 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e  rtual table bein
2fd20 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a  g queried..**.**
2fd30 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   Information abo
2fd40 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  ut the ORDER BY 
2fd50 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64  clause is stored
2fd60 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a   in aOrderBy[]..
2fd70 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66 20  ** Each term of 
2fd80 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73  aOrderBy records
2fd90 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65   a column of the
2fda0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
2fdb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65  ..**.** The [xBe
2fdc0 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20  stIndex] method 
2fdd0 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74  must fill aConst
2fde0 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74  raintUsage[] wit
2fdf0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2fe00 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61   about what para
2fe10 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74  meters to pass t
2fe20 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20 61  o xFilter.  If a
2fe30 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a  rgvIndex>0 then.
2fe40 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  ** the right-han
2fe50 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f  d side of the co
2fe60 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e  rresponding aCon
2fe70 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61  straint[] is eva
2fe80 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65  luated.** and be
2fe90 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e  comes the argvIn
2fea0 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20  dex-th entry in 
2feb0 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73 74  argv.  If aConst
2fec0 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69  raintUsage[].omi
2fed0 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68  t.** is true, th
2fee0 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  en the constrain
2fef0 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20  t is assumed to 
2ff00 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64  be fully handled
2ff10 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75   by the.** virtu
2ff20 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20  al table and is 
2ff30 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69  not checked agai
2ff40 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  n by SQLite..**.
2ff50 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61 6e  ** The idxNum an
2ff60 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20  d idxPtr values 
2ff70 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64  are recorded and
2ff80 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
2ff90 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65  .** [xFilter] me
2ffa0 74 68 6f 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65  thod..** [sqlite
2ffb0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65  3_free()] is use
2ffc0 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72  d to free idxPtr
2ffd0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 66   if and only iff
2ffe0 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64  .** needToFreeId
2fff0 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a  xPtr is true..**
30000 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43  .** The orderByC
30010 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68  onsumed means th
30020 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b  at output from [
30030 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d  xFilter]/[xNext]
30040 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a   will occur in.*
30050 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72  * the correct or
30060 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74  der to satisfy t
30070 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
30080 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65  se so that no se
30090 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e  parate.** sortin
300a0 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72  g step is requir
300b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73  ed..**.** The es
300c0 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75  timatedCost valu
300d0 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  e is an estimate
300e0 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20   of the cost of 
300f0 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72  doing the.** par
30100 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20  ticular lookup. 
30110 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20   A full scan of 
30120 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65  a table with N e
30130 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
30140 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20  ve.** a cost of 
30150 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61  N.  A binary sea
30160 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f  rch of a table o
30170 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  f N entries shou
30180 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73  ld have a.** cos
30190 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65  t of approximate
301a0 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74  ly log(N)..*/.st
301b0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
301c0 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49  ex_info {.  /* I
301d0 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  nputs */.  int n
301e0 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
301f0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
30200 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43  of entries in aC
30210 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73  onstraint */.  s
30220 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
30230 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b  dex_constraint {
30240 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
30250 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
30260 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66  /* Column on lef
30270 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63  t-hand side of c
30280 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20  onstraint */.   
30290 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
302a0 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
302b0 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
302c0 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  or */.     unsig
302d0 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
302e0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
302f0 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
30300 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
30310 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65    int iTermOffse
30320 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55  t;          /* U
30330 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d  sed internally -
30340 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75   xBestIndex shou
30350 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d  ld ignore */.  }
30360 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20   *aConstraint;  
30370 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62            /* Tab
30380 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75  le of WHERE clau
30390 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a  se constraints *
303a0 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79  /.  int nOrderBy
303b0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
303c0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  * Number of term
303d0 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42  s in the ORDER B
303e0 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74  Y clause */.  st
303f0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
30400 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20  ex_orderby {.   
30410 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
30420 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
30430 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  olumn number */.
30440 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
30450 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f  ar desc;       /
30460 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e  * True for DESC.
30470 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e    False for ASC.
30480 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42   */.  } *aOrderB
30490 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
304a0 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59   /* The ORDER BY
304b0 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20   clause */.  /* 
304c0 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72  Outputs */.  str
304d0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
304e0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61  x_constraint_usa
304f0 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67  ge {.    int arg
30500 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20  vIndex;         
30510 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73    /* if >0, cons
30520 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f  traint is part o
30530 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65  f argv to xFilte
30540 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65  r */.    unsigne
30550 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20  d char omit;    
30560 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
30570 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
30580 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
30590 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55   } *aConstraintU
305a0 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
305b0 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
305c0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
305d0 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
305e0 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
305f0 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
30600 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
30610 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
30620 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
30630 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
30640 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
30650 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
30660 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
30670 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
30680 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
30690 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
306a0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
306b0 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
306c0 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
306d0 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
306e0 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
306f0 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
30700 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
30710 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51  */.};.#define SQ
30720 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
30730 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
30740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
30750 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
30760 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
30770 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
30780 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
30790 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
307a0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
307b0 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
307c0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
307d0 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
307e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
307f0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
30800 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
30810 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
30820 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  er A Virtual Tab
30830 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le Implementatio
30840 6e 20 7b 48 31 38 32 30 30 7d 20 3c 53 32 30 34  n {H18200} <S204
30850 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
30860 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  TAL.**.** This r
30870 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74  outine is used t
30880 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
30890 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
308a0 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a  module] name..**
308b0 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75   Module names mu
308c0 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64  st be registered
308d0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74   before.** creat
308e0 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75  ing a new [virtu
308f0 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20  al table] using 
30900 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62  the module, or b
30910 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a  efore using a.**
30920 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69   preexisting [vi
30930 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72  rtual table] for
30940 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
30950 2a 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61  ** The module na
30960 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64  me is registered
30970 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
30980 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
30990 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
309a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
309b0 72 2e 20 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  r.  The name of 
309c0 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69  the module is gi
309d0 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73  ven by the .** s
309e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
309f0 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
30a00 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
30a10 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70  er to.** the imp
30a20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
30a30 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  he [virtual tabl
30a40 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 54 68 65  e module].   The
30a50 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d   fourth.** param
30a60 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
30a70 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61  rary client data
30a80 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
30a90 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a   passed through.
30aa0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72  ** into the [xCr
30ab0 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e  eate] and [xConn
30ac0 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20  ect] methods of 
30ad0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
30ae0 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e  e module.** when
30af0 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74   a new virtual t
30b00 61 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67  able is be being
30b10 20 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e   created or rein
30b20 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  itialized..**.**
30b30 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
30b40 68 61 73 20 65 78 61 63 74 6c 79 20 74 68 65 20  has exactly the 
30b50 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 63  same effect as c
30b60 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  alling.** [sqlit
30b70 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
30b80 5f 76 32 28 29 5d 20 77 69 74 68 20 61 20 4e 55  _v2()] with a NU
30b90 4c 4c 20 63 6c 69 65 6e 74 20 64 61 74 61 20 64  LL client data d
30ba0 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51  estructor..*/.SQ
30bb0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
30bc0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  L int sqlite3_cr
30bd0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
30be0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
30bf0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
30c00 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
30c10 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
30c20 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
30c30 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
30c40 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
30c50 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
30c60 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
30c70 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
30c80 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
30c90 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
30ca0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
30cb0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
30cc0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
30cd0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
30ce0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30cf0 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72  : Register A Vir
30d00 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65  tual Table Imple
30d10 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 31  mentation {H1821
30d20 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45  0} <S20400>.** E
30d30 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
30d40 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  * This routine i
30d50 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 74  s identical to t
30d60 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
30d70 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65 74  te_module()] met
30d80 68 6f 64 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74  hod,.** except t
30d90 68 61 74 20 69 74 20 68 61 73 20 61 6e 20 65 78  hat it has an ex
30da0 74 72 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tra parameter to
30db0 20 73 70 65 63 69 66 79 20 0a 2a 2a 20 61 20 64   specify .** a d
30dc0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
30dd0 6f 6e 20 66 6f 72 20 74 68 65 20 63 6c 69 65 6e  on for the clien
30de0 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  t data pointer. 
30df0 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
30e00 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
30e10 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28  uctor function (
30e20 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  if it is not NUL
30e30 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a  L) when SQLite.*
30e40 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  * no longer need
30e50 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  s the pClientDat
30e60 61 20 70 6f 69 6e 74 65 72 2e 20 20 0a 2a 2f 0a  a pointer.  .*/.
30e70 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
30e80 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
30e90 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
30ea0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
30eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
30ec0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
30ed0 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
30ee0 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
30ef0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
30f00 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
30f10 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
30f20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
30f30 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20  ite3_module *p, 
30f40 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
30f50 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
30f60 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61   void *pClientDa
30f70 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43  ta,         /* C
30f80 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
30f90 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
30fa0 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  */.  void(*xDest
30fb0 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20  roy)(void*)     
30fc0 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75  /* Module destru
30fd0 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  ctor function */
30fe0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
30ff0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
31000 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65  le Instance Obje
31010 63 74 20 7b 48 31 38 30 31 30 7d 20 3c 53 32 30  ct {H18010} <S20
31020 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  400>.** KEYWORDS
31030 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a  : sqlite3_vtab.*
31040 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
31050 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74  *.** Every [virt
31060 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
31070 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ] implementation
31080 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
31090 0a 2a 2a 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  .** of the follo
310a0 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74  wing structure t
310b0 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72  o describe a par
310c0 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
310d0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74  .** of the [virt
310e0 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63  ual table].  Eac
310f0 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a  h subclass will.
31100 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74  ** be tailored t
31110 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
31120 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  eeds of the modu
31130 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
31140 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73  n..** The purpos
31150 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63  e of this superc
31160 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e  lass is to defin
31170 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73  e certain fields
31180 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d   that are.** com
31190 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c  mon to all modul
311a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
311b0 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c  s..**.** Virtual
311c0 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
311d0 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
311e0 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
311f0 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
31200 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
31210 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
31220 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ()] to zErrMsg. 
31230 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
31240 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
31250 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
31260 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
31270 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
31280 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
31290 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69  prior to assigni
312a0 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20  ng a new string 
312b0 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74  to zErrMsg.  Aft
312c0 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
312d0 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76  sage.** is deliv
312e0 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63  ered up to the c
312f0 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f  lient applicatio
31300 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  n, the string wi
31310 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
31320 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20  lly.** freed by 
31330 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61  sqlite3_free() a
31340 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66  nd the zErrMsg f
31350 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72  ield will be zer
31360 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  oed..*/.struct s
31370 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20  qlite3_vtab {.  
31380 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
31390 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20  dule *pModule;  
313a0 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f  /* The module fo
313b0 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74  r this virtual t
313c0 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52  able */.  int nR
313d0 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ef;             
313e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20            /* NO 
313f0 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20  LONGER USED */. 
31400 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
31410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31420 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
31430 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
31440 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
31450 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
31460 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
31470 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
31480 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
31490 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
314a0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
314b0 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20  al Table Cursor 
314c0 4f 62 6a 65 63 74 20 20 7b 48 31 38 30 32 30 7d  Object  {H18020}
314d0 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59   <S20400>.** KEY
314e0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
314f0 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74  tab_cursor {virt
31500 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72  ual table cursor
31510 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  }.** EXPERIMENTA
31520 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76  L.**.** Every [v
31530 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
31540 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ule] implementat
31550 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
31560 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ass of the.** fo
31570 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
31580 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  e to describe cu
31590 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
315a0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69   into the.** [vi
315b0 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64  rtual table] and
315c0 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20   are used.** to 
315d0 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65  loop through the
315e0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20   virtual table. 
315f0 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65   Cursors are cre
31600 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ated using the.*
31610 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  * [sqlite3_modul
31620 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d  e.xOpen | xOpen]
31630 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d   method of the m
31640 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65  odule and are de
31650 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68  stroyed.** by th
31660 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  e [sqlite3_modul
31670 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73  e.xClose | xClos
31680 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 73 73  e] method.  Cuss
31690 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  ors are used.** 
316a0 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d  by the [xFilter]
316b0 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66  , [xNext], [xEof
316c0 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e  ], [xColumn], an
316d0 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f  d [xRowid] metho
316e0 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64  ds.** of the mod
316f0 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  ule.  Each modul
31700 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
31710 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20   will define.** 
31720 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61  the content of a
31730 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72   cursor structur
31740 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77  e to suit its ow
31750 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  n needs..**.** T
31760 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65  his superclass e
31770 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74  xists in order t
31780 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20  o define fields 
31790 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68  of the cursor th
317a0 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e  at.** are common
317b0 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e   to all implemen
317c0 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75  tations..*/.stru
317d0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
317e0 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74  cursor {.  sqlit
317f0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20  e3_vtab *pVtab; 
31800 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20       /* Virtual 
31810 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75  table of this cu
31820 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  rsor */.  /* Vir
31830 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
31840 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
31850 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
31860 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
31870 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
31880 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54  I3REF: Declare T
31890 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56  he Schema Of A V
318a0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48 31  irtual Table {H1
318b0 38 32 38 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a  8280} <S20400>.*
318c0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
318d0 2a 0a 2a 2a 20 54 68 65 20 5b 78 43 72 65 61 74  *.** The [xCreat
318e0 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
318f0 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a  ] methods of a.*
31900 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
31910 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68   module] call th
31920 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  is interface.** 
31930 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
31940 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
31950 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
31960 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
31970 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
31980 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
31990 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54  lement..*/.SQLIT
319a0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
319b0 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  nt sqlite3_decla
319c0 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a  re_vtab(sqlite3*
319d0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
319e0 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  QL);../*.** CAPI
319f0 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41  3REF: Overload A
31a00 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20   Function For A 
31a10 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48  Virtual Table {H
31a20 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18300} <S20400>.
31a30 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
31a40 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
31a50 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65  bles can provide
31a60 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
31a70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
31a80 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69  functions.** usi
31a90 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e  ng the [xFindFun
31aa0 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66  ction] method of
31ab0 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
31ac0 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a  ble module].  .*
31ad0 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72  * But global ver
31ae0 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
31af0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
31b00 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
31b10 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
31b20 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
31b30 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
31b40 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
31b50 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
31b60 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
31b70 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
31b80 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
31b90 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
31ba0 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
31bb0 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
31bc0 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
31bd0 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
31be0 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
31bf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
31c00 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
31c10 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
31c20 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
31c30 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
31c40 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
31c50 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
31c60 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
31c70 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
31c80 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
31c90 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
31ca0 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
31cb0 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
31cc0 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b  loaded.** by a [
31cd0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
31ce0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
31cf0 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
31d00 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63  e3_overload_func
31d10 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63  tion(sqlite3*, c
31d20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
31d30 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b  Name, int nArg);
31d40 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ../*.** The inte
31d50 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
31d60 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
31d70 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f  nism defined abo
31d80 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74  ve (back up.** t
31d90 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61  o a comment rema
31da0 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74  rkably similar t
31db0 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63  o this one) is c
31dc0 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
31dd0 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
31de0 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
31df0 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
31e00 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
31e10 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
31e20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
31e30 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
31e40 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
31e50 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
31e60 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
31e70 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
31e80 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
31e90 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
31ea0 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
31eb0 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
31ec0 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
31ed0 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
31ee0 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
31ef0 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45  ..**.****** EXPE
31f00 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65  RIMENTAL - subje
31f10 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74  ct to change wit
31f20 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a  hout notice ****
31f30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f  **********.*/../
31f40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
31f50 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70   Handle To An Op
31f60 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 30 30 7d  en BLOB {H17800}
31f70 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 45 59   <S30230>.** KEY
31f80 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e  WORDS: {BLOB han
31f90 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  dle} {BLOB handl
31fa0 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  es}.**.** An ins
31fb0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
31fc0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
31fd0 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20  an open BLOB on 
31fe0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
31ff0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
32000 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
32010 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f  /O] can be perfo
32020 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73  rmed..** Objects
32030 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72   of this type ar
32040 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  e created by [sq
32050 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
32060 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f  )].** and destro
32070 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
32080 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
32090 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * The [sqlite3_b
320a0 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
320b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
320c0 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
320d0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
320e0 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
320f0 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
32100 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ons of the BLOB.
32110 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
32120 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
32130 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32140 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
32150 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a   BLOB in bytes..
32160 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
32170 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73  t sqlite3_blob s
32180 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a  qlite3_blob;../*
32190 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
321a0 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e  en A BLOB For In
321b0 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 48  cremental I/O {H
321c0 31 37 38 31 30 7d 20 3c 53 33 30 32 33 30 3e 0a  17810} <S30230>.
321d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
321e0 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42  faces opens a [B
321f0 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e  LOB handle | han
32200 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42  dle] to the BLOB
32210 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72   located.** in r
32220 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20  ow iRow, column 
32230 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a  zColumn, table z
32240 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73  Table in databas
32250 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68  e zDb;.** in oth
32260 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61  er words, the sa
32270 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75  me BLOB that wou
32280 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62  ld be selected b
32290 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  y:.**.** <pre>.*
322a0 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f  *     SELECT zCo
322b0 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54  lumn FROM zDb.zT
322c0 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69  able WHERE [rowi
322d0 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f  d] = iRow;.** </
322e0 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  pre> {END}.**.**
322f0 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61   If the flags pa
32300 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a  rameter is non-z
32310 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c  ero, then the BL
32320 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  OB is opened for
32330 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69   read.** and wri
32340 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69 74  te access. If it
32350 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c   is zero, the BL
32360 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  OB is opened for
32370 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a   read access..**
32380 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
32390 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
323a0 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e  is not the filen
323b0 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ame that contain
323c0 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  s.** the databas
323d0 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65  e but rather the
323e0 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f   symbolic name o
323f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  f the database t
32400 68 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e  hat.** is assign
32410 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  ed when the data
32420 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65  base is connecte
32430 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d  d using [ATTACH]
32440 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61 69  ..** For the mai
32450 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  n database file,
32460 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
32470 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a  me is "main"..**
32480 20 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73   For TEMP tables
32490 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  , the database n
324a0 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a  ame is "temp"..*
324b0 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
324c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
324d0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65  returned and the
324e0 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   new [BLOB handl
324f0 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  e] is written.**
32500 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68   to *ppBlob. Oth
32510 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
32520 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
32530 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69  ed and *ppBlob i
32540 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61  s set.** to be a
32550 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 0a 2a   null pointer..*
32560 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
32570 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61  sets the [databa
32580 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65  se connection] e
32590 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
325a0 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69  ssage.** accessi
325b0 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
325c0 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20  _errcode()] and 
325d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
325e0 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a  )] and related.*
325f0 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 4e 6f  * functions.  No
32600 74 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42  te that the *ppB
32610 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20  lob variable is 
32620 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a  always initializ
32630 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74  ed in a.** way t
32640 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66  hat makes it saf
32650 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  e to invoke [sql
32660 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
32670 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a  )] on *ppBlob.**
32680 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
32690 68 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  he success or fa
326a0 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f  ilure of this ro
326b0 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  utine..**.** If 
326c0 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42  the row that a B
326d0 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74  LOB handle point
326e0 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64  s to is modified
326f0 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54   by an.** [UPDAT
32700 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72  E], [DELETE], or
32710 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54   by [ON CONFLICT
32720 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a  ] side-effects.*
32730 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  * then the BLOB 
32740 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64  handle is marked
32750 20 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a   as "expired"..*
32760 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69  * This is true i
32770 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20  f any column of 
32780 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67  the row is chang
32790 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d  ed, even a colum
327a0 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  n.** other than 
327b0 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42  the one the BLOB
327c0 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20   handle is open 
327d0 6f 6e 2e 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20  on..** Calls to 
327e0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
327f0 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
32800 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
32810 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65   for.** a expire
32820 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61  d BLOB handle fa
32830 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72  il with an retur
32840 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  n code of [SQLIT
32850 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61  E_ABORT]..** Cha
32860 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74  nges written int
32870 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74  o a BLOB prior t
32880 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72  o the BLOB expir
32890 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  ing are not.** r
328a0 6f 6c 6c 62 61 63 6b 20 62 79 20 74 68 65 20 65  ollback by the e
328b0 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  xpiration of the
328c0 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61   BLOB.  Such cha
328d0 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  nges will eventu
328e0 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69  ally.** commit i
328f0 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  f the transactio
32900 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  n continues to c
32910 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
32920 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
32930 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
32940 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74  interface to det
32950 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20  ermine the size 
32960 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64  of.** the opened
32970 20 62 6c 6f 62 2e 20 20 54 68 65 20 73 69 7a 65   blob.  The size
32980 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e   of a blob may n
32990 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ot be changed by
329a0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
329b0 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50  ce.  Use the [UP
329c0 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e  DATE] SQL comman
329d0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
329e0 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f  size of a.** blo
329f0 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  b..**.** The [sq
32a00 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
32a10 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lob()] and [sqli
32a20 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
32a30 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65  lob()] interface
32a40 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69  s.** and the bui
32a50 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d  lt-in [zeroblob]
32a60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61   SQL function ca
32a70 6e 20 62 65 20 75 73 65 64 2c 20 69 66 20 64 65  n be used, if de
32a80 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65  sired,.** to cre
32a90 61 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65  ate an empty, ze
32aa0 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69  ro-filled blob i
32ab0 6e 20 77 68 69 63 68 20 74 6f 20 72 65 61 64 20  n which to read 
32ac0 6f 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a  or write using.*
32ad0 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  * this interface
32ae0 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  ..**.** To avoid
32af0 20 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b   a resource leak
32b00 2c 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c  , every open [BL
32b10 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c  OB handle] shoul
32b20 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20  d eventually.** 
32b30 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 61  be released by a
32b40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
32b50 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
32b60 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
32b70 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 31 33 5d  nts:.** [H17813]
32b80 20 5b 48 31 37 38 31 34 5d 20 5b 48 31 37 38 31   [H17814] [H1781
32b90 36 5d 20 5b 48 31 37 38 31 39 5d 20 5b 48 31 37  6] [H17819] [H17
32ba0 38 32 31 5d 20 5b 48 31 37 38 32 34 5d 0a 2a 2f  821] [H17824].*/
32bb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
32bc0 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65  b_open(.  sqlite
32bd0 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  3*,.  const char
32be0 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63   *zDb,.  const c
32bf0 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63  har *zTable,.  c
32c00 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
32c10 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e  mn,.  sqlite3_in
32c20 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20  t64 iRow,.  int 
32c30 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33  flags,.  sqlite3
32c40 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29  _blob **ppBlob.)
32c50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32c60 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20  F: Close A BLOB 
32c70 48 61 6e 64 6c 65 20 7b 48 31 37 38 33 30 7d 20  Handle {H17830} 
32c80 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43  <S30230>.**.** C
32c90 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42  loses an open [B
32ca0 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a  LOB handle]..**.
32cb0 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f  ** Closing a BLO
32cc0 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68  B shall cause th
32cd0 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  e current transa
32ce0 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a  ction to commit.
32cf0 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20  ** if there are 
32d00 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20  no other BLOBs, 
32d10 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61  no pending prepa
32d20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  red statements, 
32d30 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  and the.** datab
32d40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
32d50 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74  s in [autocommit
32d60 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e   mode]..** If an
32d70 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61  y writes were ma
32d80 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20  de to the BLOB, 
32d90 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65  they might be he
32da0 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75  ld in cache.** u
32db0 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f  ntil the close o
32dc0 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79  peration if they
32dd0 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a   will fit..**.**
32de0 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f   Closing the BLO
32df0 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74  B often forces t
32e00 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75  he changes.** ou
32e10 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f  t to disk and so
32e20 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f   if any I/O erro
32e30 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77  rs occur, they w
32e40 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72  ill likely occur
32e50 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20  .** at the time 
32e60 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  when the BLOB is
32e70 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72   closed.  Any er
32e80 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
32e90 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e  during.** closin
32ea0 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61  g are reported a
32eb0 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74  s a non-zero ret
32ec0 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  urn value..**.**
32ed0 20 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f   The BLOB is clo
32ee0 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61  sed unconditiona
32ef0 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68  lly.  Even if th
32f00 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
32f10 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63  ns.** an error c
32f20 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73  ode, the BLOB is
32f30 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a   still closed..*
32f40 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69  *.** Calling thi
32f50 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
32f60 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 77   null pointer (w
32f70 68 69 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65  hich as would be
32f80 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
32f90 66 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b  failed call to [
32fa0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
32fb0 6e 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c  n()]) is a harml
32fc0 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
32fd0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
32fe0 2a 20 5b 48 31 37 38 33 33 5d 20 5b 48 31 37 38  * [H17833] [H178
32ff0 33 36 5d 20 5b 48 31 37 38 33 39 5d 0a 2a 2f 0a  36] [H17839].*/.
33000 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
33010 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62  _close(sqlite3_b
33020 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
33030 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20  API3REF: Return 
33040 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f  The Size Of An O
33050 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 34 30  pen BLOB {H17840
33060 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a  } <S30230>.**.**
33070 20 52 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   Returns the siz
33080 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68  e in bytes of th
33090 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c  e BLOB accessibl
330a0 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 75  e via the .** su
330b0 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65  ccessfully opene
330c0 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  d [BLOB handle] 
330d0 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75  in its only argu
330e0 6d 65 6e 74 2e 20 20 54 68 65 0a 2a 2a 20 69 6e  ment.  The.** in
330f0 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49  cremental blob I
33100 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  /O routines can 
33110 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65  only read or ove
33120 72 77 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e  rwriting existin
33130 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e  g.** blob conten
33140 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63  t; they cannot c
33150 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f  hange the size o
33160 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20  f a blob..**.** 
33170 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
33180 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
33190 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
331a0 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
331b0 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
331c0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
331d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
331e0 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
331f0 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
33200 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
33210 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
33220 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
33230 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
33240 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
33250 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
33260 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
33270 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
33280 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
33290 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
332a0 3a 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f  :.** [H17843].*/
332b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
332c0 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  b_bytes(sqlite3_
332d0 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  blob *);../*.** 
332e0 43 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44  CAPI3REF: Read D
332f0 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20  ata From A BLOB 
33300 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48  Incrementally {H
33310 31 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a  17850} <S30230>.
33320 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
33330 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72  ion is used to r
33340 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e  ead data from an
33350 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
33360 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61  le] into a.** ca
33370 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75  ller-supplied bu
33380 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66  ffer. N bytes of
33390 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64   data are copied
333a0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a   into buffer Z.*
333b0 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20  * from the open 
333c0 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61  BLOB, starting a
333d0 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  t offset iOffset
333e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65  ..**.** If offse
333f0 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
33400 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66  s than N bytes f
33410 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
33420 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c  he BLOB,.** [SQL
33430 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
33440 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
33450 74 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20  ta is read.  If 
33460 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a  N or iOffset is.
33470 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  ** less than zer
33480 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  o, [SQLITE_ERROR
33490 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
334a0 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61  d no data is rea
334b0 64 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f  d..** The size o
334c0 66 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20  f the blob (and 
334d0 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75  hence the maximu
334e0 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66  m value of N+iOf
334f0 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20  fset).** can be 
33500 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
33510 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   the [sqlite3_bl
33520 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
33530 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  rface..**.** An 
33540 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
33550 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20  from an expired 
33560 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61  [BLOB handle] fa
33570 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65  ils with an.** e
33580 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
33590 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
335a0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53  ** On success, S
335b0 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
335c0 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  rned..** Otherwi
335d0 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  se, an [error co
335e0 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e  de] or an [exten
335f0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
33600 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
33610 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
33620 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
33630 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
33640 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
33650 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
33660 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
33670 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
33680 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
33690 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
336a0 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
336b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
336c0 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
336d0 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
336e0 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
336f0 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
33700 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
33710 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
33720 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
33730 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
33740 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
33750 72 69 74 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52  rite()]..**.** R
33760 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
33770 5b 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36  [H17853] [H17856
33780 5d 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38  ] [H17859] [H178
33790 36 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31  62] [H17863] [H1
337a0 37 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a  7865] [H17868].*
337b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
337c0 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f  ob_read(sqlite3_
337d0 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c  blob *, void *Z,
337e0 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66   int N, int iOff
337f0 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  set);../*.** CAP
33800 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74  I3REF: Write Dat
33810 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e  a Into A BLOB In
33820 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37  crementally {H17
33830 38 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  870} <S30230>.**
33840 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
33850 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69  n is used to wri
33860 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20  te data into an 
33870 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
33880 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c  e] from a.** cal
33890 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
338a0 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20  fer. N bytes of 
338b0 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20  data are copied 
338c0 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20  from the buffer 
338d0 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70  Z.** into the op
338e0 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e  en BLOB, startin
338f0 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
33900 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  set..**.** If th
33910 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  e [BLOB handle] 
33920 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
33930 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73  rst argument was
33940 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a   not opened for.
33950 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20  ** writing (the 
33960 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
33970 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
33980 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72  _open()] was zer
33990 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63  o),.** this func
339a0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
339b0 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a  LITE_READONLY]..
339c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
339d0 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64  ion may only mod
339e0 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73  ify the contents
339f0 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74   of the BLOB; it
33a00 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69   is.** not possi
33a10 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20  ble to increase 
33a20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c  the size of a BL
33a30 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50  OB using this AP
33a40 49 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20  I..** If offset 
33a50 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20  iOffset is less 
33a60 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f  than N bytes fro
33a70 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  m the end of the
33a80 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54   BLOB,.** [SQLIT
33a90 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
33aa0 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
33ab0 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66   is written.  If
33ac0 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
33ad0 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f  an zero [SQLITE_
33ae0 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
33af0 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
33b00 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68  s written..** Th
33b10 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c  e size of the BL
33b20 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68  OB (and hence th
33b30 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20  e maximum value 
33b40 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a  of N+iOffset).**
33b50 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
33b60 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ed using the [sq
33b70 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
33b80 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
33b90 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20  *.** An attempt 
33ba0 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65  to write to an e
33bb0 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e  xpired [BLOB han
33bc0 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20  dle] fails with 
33bd0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
33be0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
33bf0 54 5d 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  T].  Writes to t
33c00 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63  he BLOB that occ
33c10 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20  urred.** before 
33c20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  the [BLOB handle
33c30 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f  ] expired are no
33c40 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79  t rolled back by
33c50 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69   the.** expirati
33c60 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65  on of the handle
33c70 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
33c80 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  se those changes
33c90 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62   might.** have b
33ca0 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20  een overwritten 
33cb0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
33cc0 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68   that expired th
33cd0 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a  e BLOB handle.**
33ce0 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64   or by other ind
33cf0 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65  ependent stateme
33d00 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  nts..**.** On su
33d10 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b  ccess, SQLITE_OK
33d20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
33d30 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20   Otherwise, an  
33d40 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
33d50 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  an [extended err
33d60 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
33d70 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rned..**.** This
33d80 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f   routine only wo
33d90 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68  rks on a [BLOB h
33da0 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73  andle] which has
33db0 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a   been created.**
33dc0 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63   by a prior succ
33dd0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
33de0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
33df0 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68  n()] and which h
33e00 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63  as not.** been c
33e10 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  losed by [sqlite
33e20 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
33e30 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74    Passing any ot
33e40 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a  her pointer in.*
33e50 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  * to this routin
33e60 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  e results in und
33e70 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
33e80 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20  bly undesirable 
33e90 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
33ea0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
33eb0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e  e3_blob_read()].
33ec0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
33ed0 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 5d  nts:.** [H17873]
33ee0 20 5b 48 31 37 38 37 34 5d 20 5b 48 31 37 38 37   [H17874] [H1787
33ef0 35 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48 31 37  5] [H17876] [H17
33f00 38 37 37 5d 20 5b 48 31 37 38 37 39 5d 20 5b 48  877] [H17879] [H
33f10 31 37 38 38 32 5d 20 5b 48 31 37 38 38 35 5d 0a  17882] [H17885].
33f20 2a 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a 69  ** [H17888].*/.i
33f30 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
33f40 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c  write(sqlite3_bl
33f50 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ob *, const void
33f60 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20   *z, int n, int 
33f70 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
33f80 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
33f90 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f  al File System O
33fa0 62 6a 65 63 74 73 20 7b 48 31 31 32 30 30 7d 20  bjects {H11200} 
33fb0 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S20100>.**.** A
33fc0 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73   virtual filesys
33fd0 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20  tem (VFS) is an 
33fe0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
33ff0 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ject.** that SQL
34000 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65  ite uses to inte
34010 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65  ract.** with the
34020 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
34030 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d  ating system.  M
34040 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64  ost SQLite build
34050 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
34060 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
34070 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
34080 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
34090 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
340a0 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
340b0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
340c0 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
340d0 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
340e0 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
340f0 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
34100 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
34110 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
34120 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
34130 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
34140 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46   pointer to a VF
34150 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  S given its name
34160 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 63  ..** Names are c
34170 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a  ase sensitive..*
34180 2a 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f  * Names are zero
34190 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
341a0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66  8 strings..** If
341b0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74   there is no mat
341c0 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ch, a NULL point
341d0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
341e0 2a 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69  ** If zVfsName i
341f0 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
34200 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72  default VFS is r
34210 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e  eturned..**.** N
34220 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67  ew VFSes are reg
34230 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c  istered with sql
34240 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
34250 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77  r()..** Each new
34260 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65   VFS becomes the
34270 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20   default VFS if 
34280 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
34290 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65  g is set..** The
342a0 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65   same VFS can be
342b0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
342c0 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f  iple times witho
342d0 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f  ut injury..** To
342e0 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e   make an existin
342f0 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64  g VFS into the d
34300 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69  efault VFS, regi
34310 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a  ster it again.**
34320 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66   with the makeDf
34330 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66  lt flag set.  If
34340 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56   two different V
34350 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a  FSes with the.**
34360 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72   same name are r
34370 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62  egistered, the b
34380 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
34390 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56  ined.  If a.** V
343a0 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64  FS is registered
343b0 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61   with a name tha
343c0 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  t is NULL or an 
343d0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a  empty string,.**
343e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
343f0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
34400 0a 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65  .**.** Unregiste
34410 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65  r a VFS with the
34420 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72   sqlite3_vfs_unr
34430 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66  egister() interf
34440 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64  ace..** If the d
34450 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e  efault VFS is un
34460 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74  registered, anot
34470 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65  her VFS is chose
34480 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61  n as.** the defa
34490 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65  ult.  The choice
344a0 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53   for the new VFS
344b0 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a   is arbitrary..*
344c0 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
344d0 73 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20 5b  s:.** [H11203] [
344e0 48 31 31 32 30 36 5d 20 5b 48 31 31 32 30 39 5d  H11206] [H11209]
344f0 20 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 32 31   [H11212] [H1121
34500 35 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 73  5] [H11218].*/.s
34510 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69  qlite3_vfs *sqli
34520 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e  te3_vfs_find(con
34530 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d  st char *zVfsNam
34540 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
34550 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c  vfs_register(sql
34560 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
34570 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71  akeDflt);.int sq
34580 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
34590 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
345a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
345b0 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 48 31  REF: Mutexes {H1
345c0 37 30 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  7000} <S20000>.*
345d0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
345e0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
345f0 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72  routines for thr
34600 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69  ead.** synchroni
34610 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74  zation. Though t
34620 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64  hey are intended
34630 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
34640 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20   use by SQLite, 
34650 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  code that links 
34660 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69  against SQLite i
34670 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74  s.** permitted t
34680 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65  o use any of the
34690 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
346a0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f  ** The SQLite so
346b0 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69  urce code contai
346c0 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  ns multiple impl
346d0 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f  ementations.** o
346e0 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f  f these mutex ro
346f0 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72  utines.  An appr
34700 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e  opriate implemen
34710 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c  tation.** is sel
34720 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61  ected automatica
34730 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  lly at compile-t
34740 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  ime.  The follow
34750 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ing.** implement
34760 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ations are avail
34770 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69  able in the SQLi
34780 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c  te core:.**.** <
34790 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  ul>.** <li>   SQ
347a0 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a  LITE_MUTEX_OS2.*
347b0 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
347c0 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a  MUTEX_PTHREAD.**
347d0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
347e0 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_W32.** <li>
347f0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
34800 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NOOP.** </ul>.**
34810 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d  .** The SQLITE_M
34820 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d  UTEX_NOOP implem
34830 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65  entation is a se
34840 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  t of routines.**
34850 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65   that does no re
34860 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69  al locking and i
34870 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
34880 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69  r use in.** a si
34890 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70  ngle-threaded ap
348a0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
348b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32  SQLITE_MUTEX_OS2
348c0 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  ,.** SQLITE_MUTE
348d0 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53  X_PTHREAD, and S
348e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20  QLITE_MUTEX_W32 
348f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
34900 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61  ** are appropria
34910 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53  te for use on OS
34920 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69  /2, Unix, and Wi
34930 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ndows..**.** If 
34940 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
34950 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
34960 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
34970 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
34980 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
34990 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
349a0 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
349b0 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
349c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
349d0 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
349e0 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e   the library. In
349f0 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a   this case the.*
34a00 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  * application mu
34a10 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74  st supply a cust
34a20 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  om mutex impleme
34a30 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  ntation using th
34a40 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
34a50 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
34a60 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  n of the sqlite3
34a70 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69  _config() functi
34a80 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c  on.** before cal
34a90 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69  ling sqlite3_ini
34aa0 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79  tialize() or any
34ab0 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71   other public sq
34ac0 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69  lite3_.** functi
34ad0 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71  on that calls sq
34ae0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
34af0 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31  ()..**.** {H1701
34b00 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  1} The sqlite3_m
34b10 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75  utex_alloc() rou
34b20 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61  tine allocates a
34b30 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e   new.** mutex an
34b40 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
34b50 74 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 37 30  ter to it. {H170
34b60 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e  12} If it return
34b70 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d  s NULL.** that m
34b80 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65  eans that a mute
34b90 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61  x could not be a
34ba0 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 30 31  llocated. {H1701
34bb0 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  3} SQLite.** wil
34bc0 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61  l unwind its sta
34bd0 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e  ck and return an
34be0 20 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d   error. {H17014}
34bf0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   The argument.**
34c00 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
34c10 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65  x_alloc() is one
34c20 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
34c30 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a  r constants:.**.
34c40 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
34c50 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
34c60 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ST.** <li>  SQLI
34c70 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
34c80 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
34c90 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
34ca0 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20  MASTER.** <li>  
34cb0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
34cc0 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20  TIC_MEM.** <li> 
34cd0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
34ce0 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69  ATIC_MEM2.** <li
34cf0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
34d00 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c  STATIC_PRNG.** <
34d10 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
34d20 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20  X_STATIC_LRU.** 
34d30 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
34d40 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a  EX_STATIC_LRU2.*
34d50 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48  * </ul>.**.** {H
34d60 31 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74  17015} The first
34d70 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63   two constants c
34d80 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ause sqlite3_mut
34d90 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72  ex_alloc() to cr
34da0 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75  eate.** a new mu
34db0 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75  tex.  The new mu
34dc0 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65  tex is recursive
34dd0 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
34de0 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
34df0 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20  is used but not 
34e00 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77  necessarily so w
34e10 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
34e20 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b  _FAST is used. {
34e30 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65  END}.** The mute
34e40 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
34e50 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
34e60 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63  o make a distinc
34e70 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
34e80 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
34e90 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54  URSIVE and SQLIT
34ea0 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20  E_MUTEX_FAST if 
34eb0 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  it does.** not w
34ec0 61 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 31 36  ant to.  {H17016
34ed0 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c  } But SQLite wil
34ee0 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61  l only request a
34ef0 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
34f00 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65   in.** cases whe
34f10 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65  re it really nee
34f20 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49  ds one.  {END} I
34f30 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72  f a faster non-r
34f40 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a  ecursive mutex.*
34f50 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
34f60 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e   is available on
34f70 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f   the host platfo
34f80 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75  rm, the mutex su
34f90 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74  bsystem.** might
34fa0 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d   return such a m
34fb0 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65  utex in response
34fc0 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   to SQLITE_MUTEX
34fd0 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  _FAST..**.** {H1
34fe0 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20  7017} The other 
34ff0 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65  allowed paramete
35000 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  rs to sqlite3_mu
35010 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68  tex_alloc() each
35020 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69   return.** a poi
35030 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63  nter to a static
35040 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74   preexisting mut
35050 65 78 2e 20 7b 45 4e 44 7d 20 20 53 69 78 20 73  ex. {END}  Six s
35060 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
35070 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65  e.** used by the
35080 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
35090 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74   of SQLite.  Fut
350a0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
350b0 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64  SQLite.** may ad
350c0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61  d additional sta
350d0 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74  tic mutexes.  St
350e0 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
350f0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
35100 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f   use by SQLite o
35110 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
35120 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ns that use SQLi
35130 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  te mutexes shoul
35140 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68  d.** use only th
35150 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
35160 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  s returned by SQ
35170 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
35180 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  or.** SQLITE_MUT
35190 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a  EX_RECURSIVE..**
351a0 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74  .** {H17018} Not
351b0 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66  e that if one of
351c0 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   the dynamic mut
351d0 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53  ex parameters (S
351e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
351f0 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55  .** or SQLITE_MU
35200 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69  TEX_RECURSIVE) i
35210 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69  s used then sqli
35220 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
35230 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64  ).** returns a d
35240 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f  ifferent mutex o
35250 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b  n every call.  {
35260 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72 20  H17034} But for 
35270 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75  the static.** mu
35280 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73  tex types, the s
35290 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74  ame mutex is ret
352a0 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63  urned on every c
352b0 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  all that has.** 
352c0 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75  the same type nu
352d0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  mber..**.** {H17
352e0 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65 33  019} The sqlite3
352f0 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f  _mutex_free() ro
35300 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65  utine deallocate
35310 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  s a previously.*
35320 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61  * allocated dyna
35330 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 37 30  mic mutex. {H170
35340 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63 61  20} SQLite is ca
35350 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63  reful to dealloc
35360 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e  ate every.** dyn
35370 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20  amic mutex that 
35380 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41  it allocates. {A
35390 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61 6d  17021} The dynam
353a0 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20  ic mutexes must 
353b0 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65  not be in.** use
353c0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64   when they are d
353d0 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37  eallocated. {A17
353e0 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67 20  022} Attempting 
353f0 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20  to deallocate a 
35400 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
35410 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
35420 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 7b  ined behavior. {
35430 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20 6e  H17023} SQLite n
35440 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73  ever deallocates
35450 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74  .** a static mut
35460 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ex. {END}.**.** 
35470 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
35480 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71  x_enter() and sq
35490 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
354a0 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  ) routines attem
354b0 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61  pt.** to enter a
354c0 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 34 7d   mutex. {H17024}
354d0 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
354e0 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69  ad is already wi
354f0 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a  thin the mutex,.
35500 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
35510 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c  _enter() will bl
35520 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ock and sqlite3_
35530 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c  mutex_try() will
35540 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
35550 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 35 7d  E_BUSY. {H17025}
35560 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75    The sqlite3_mu
35570 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66  tex_try() interf
35580 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ace returns [SQL
35590 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20  ITE_OK].** upon 
355a0 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79  successful entry
355b0 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 74 65  .  {H17026} Mute
355c0 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  xes created usin
355d0 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  g.** SQLITE_MUTE
355e0 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20  X_RECURSIVE can 
355f0 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69  be entered multi
35600 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65  ple times by the
35610 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a   same thread..**
35620 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 75 63   {H17027} In suc
35630 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20  h cases the,.** 
35640 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78  mutex must be ex
35650 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75  ited an equal nu
35660 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65  mber of times be
35670 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72  fore another thr
35680 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72  ead.** can enter
35690 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66 20 74  .  {A17028} If t
356a0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74  he same thread t
356b0 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e  ries to enter an
356c0 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20  y other.** kind 
356d0 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68  of mutex more th
356e0 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68  an once, the beh
356f0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
35700 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20  ed..** {H17029} 
35710 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
35720 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63  r exhibit.** suc
35730 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74  h behavior in it
35740 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74  s own use of mut
35750 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  exes..**.** Some
35760 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78   systems (for ex
35770 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39  ample, Windows 9
35780 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72  5) do not suppor
35790 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  t the operation.
357a0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  ** implemented b
357b0 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  y sqlite3_mutex_
357c0 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65  try().  On those
357d0 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65   systems, sqlite
357e0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a  3_mutex_try().**
357f0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
35800 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  urn SQLITE_BUSY.
35810 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65 20 53    {H17030} The S
35820 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20  QLite core only 
35830 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c  ever uses.** sql
35840 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
35850 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74   as an optimizat
35860 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61  ion so this is a
35870 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 76 69  cceptable behavi
35880 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33  or..**.** {H1703
35890 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  1} The sqlite3_m
358a0 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75  utex_leave() rou
358b0 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74  tine exits a mut
358c0 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70  ex that was.** p
358d0 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65  reviously entere
358e0 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68  d by the same th
358f0 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32 7d 20  read.  {A17032} 
35900 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  The behavior.** 
35910 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20  is undefined if 
35920 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74  the mutex is not
35930 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
35940 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ed by the.** cal
35950 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69  ling thread or i
35960 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
35970 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31 37  allocated.  {H17
35980 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  033} SQLite will
35990 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74  .** never do eit
359a0 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  her. {END}.**.**
359b0 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   If the argument
359c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
359d0 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74  x_enter(), sqlit
359e0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20  e3_mutex_try(), 
359f0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  or.** sqlite3_mu
35a00 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61  tex_leave() is a
35a10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
35a20 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f  hen all three ro
35a30 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65  utines.** behave
35a40 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   as no-ops..**.*
35a50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
35a60 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
35a70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
35a80 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
35a90 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74  ..*/.sqlite3_mut
35aa0 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65  ex *sqlite3_mute
35ab0 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  x_alloc(int);.vo
35ac0 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
35ad0 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75  _free(sqlite3_mu
35ae0 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
35af0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
35b00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
35b10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
35b20 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d  ex_try(sqlite3_m
35b30 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
35b40 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
35b50 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
35b60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35b70 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73  F: Mutex Methods
35b80 20 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30 7d   Object {H17120}
35b90 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50   <S20130>.** EXP
35ba0 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
35bb0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
35bc0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65  his structure de
35bd0 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65  fines the low-le
35be0 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  vel routines.** 
35bf0 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65  used to allocate
35c00 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73   and use mutexes
35c10 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c  ..**.** Usually,
35c20 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
35c30 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ex implementatio
35c40 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53  ns provided by S
35c50 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66  QLite are.** suf
35c60 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72  ficient, however
35c70 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68   the user has th
35c80 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73  e option of subs
35c90 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f  tituting a custo
35ca0 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  m.** implementat
35cb0 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69  ion for speciali
35cc0 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20  zed deployments 
35cd0 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77  or systems for w
35ce0 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64  hich SQLite.** d
35cf0 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20  oes not provide 
35d00 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
35d10 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68  mentation. In th
35d20 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65  is case, the use
35d30 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64  r.** creates and
35d40 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e   populates an in
35d50 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
35d60 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73  tructure to pass
35d70 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
35d80 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69  onfig() along wi
35d90 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  th the [SQLITE_C
35da0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74  ONFIG_MUTEX] opt
35db0 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  ion..** Addition
35dc0 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63  ally, an instanc
35dd0 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
35de0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
35df0 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20  as an.** output 
35e00 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75  variable when qu
35e10 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65  erying the syste
35e20 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  m for the curren
35e30 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  t mutex.** imple
35e40 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67  mentation, using
35e50 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
35e60 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70  FIG_GETMUTEX] op
35e70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
35e80 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f  xMutexInit metho
35e90 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69  d defined by thi
35ea0 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69  s structure is i
35eb0 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72  nvoked as.** par
35ec0 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74  t of system init
35ed0 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68  ialization by th
35ee0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
35ef0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e  lize() function.
35f00 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 65  .** {H17001} The
35f10 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74   xMutexInit rout
35f20 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61 6c  ine shall be cal
35f30 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  led by SQLite on
35f40 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65  ce for each.** e
35f50 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
35f60 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
35f70 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  lize()]..**.** T
35f80 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74  he xMutexEnd met
35f90 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74  hod defined by t
35fa0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73  his structure is
35fb0 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70   invoked as.** p
35fc0 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68  art of system sh
35fd0 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71  utdown by the sq
35fe0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
35ff0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a   function. The.*
36000 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
36010 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20   of this method 
36020 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 72  is expected to r
36030 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74  elease all outst
36040 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72  anding.** resour
36050 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20  ces obtained by 
36060 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64  the mutex method
36070 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
36080 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20  , especially.** 
36090 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62  those obtained b
360a0 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74  y the xMutexInit
360b0 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 33   method. {H17003
360c0 7d 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28  } The xMutexEnd(
360d0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73  ).** interface s
360e0 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  hall be invoked 
360f0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61  once for each ca
36100 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
36110 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a  hutdown()]..**.*
36120 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
36130 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65  seven methods de
36140 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
36150 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 41  ructure (xMutexA
36160 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46  lloc,.** xMutexF
36170 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72  ree, xMutexEnter
36180 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75  , xMutexTry, xMu
36190 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78  texLeave, xMutex
361a0 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74  Held and.** xMut
361b0 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65  exNotheld) imple
361c0 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69  ment the followi
361d0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 72  ng interfaces (r
361e0 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a  espectively):.**
361f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
36200 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
36210 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69  ex_alloc()] </li
36220 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
36230 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
36240 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
36250 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
36260 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c  tex_enter()] </l
36270 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
36280 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
36290 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
362a0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
362b0 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c  tex_leave()] </l
362c0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
362d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
362e0 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  d()] </li>.**   
362f0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
36300 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20  utex_notheld()] 
36310 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
36320 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69  *.** The only di
36330 66 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 74  fference is that
36340 20 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69   the public sqli
36350 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e  te3_XXX function
36360 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20  s enumerated.** 
36370 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69  above silently i
36380 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61  gnore any invoca
36390 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20  tions that pass 
363a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
363b0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76  nstead.** of a v
363c0 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c  alid mutex handl
363d0 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  e. The implement
363e0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65  ations of the me
363f0 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a  thods defined.**
36400 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75   by this structu
36410 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69  re are not requi
36420 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68  red to handle th
36430 69 73 20 63 61 73 65 2c 20 74 68 65 20 72 65 73  is case, the res
36440 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69  ults.** of passi
36450 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
36460 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76  r instead of a v
36470 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c  alid mutex handl
36480 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a  e are undefined.
36490 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61  ** (i.e. it is a
364a0 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f  cceptable to pro
364b0 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  vide an implemen
364c0 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66  tation that segf
364d0 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69  aults if.** it i
364e0 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20  s passed a NULL 
364f0 70 6f 69 6e 74 65 72 29 2e 0a 2a 2a 0a 2a 2a 20  pointer)..**.** 
36500 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29  The xMutexInit()
36510 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 62 65 20   method must be 
36520 74 68 72 65 61 64 73 61 66 65 2e 20 20 49 74 20  threadsafe.  It 
36530 6d 75 73 74 20 62 65 20 68 61 72 6d 6c 65 73 73  must be harmless
36540 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 78 4d   to.** invoke xM
36550 75 74 65 78 49 6e 69 74 28 29 20 6d 75 74 69 70  utexInit() mutip
36560 6c 65 20 74 69 6d 65 73 20 77 69 74 68 69 6e 20  le times within 
36570 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
36580 20 61 6e 64 20 77 69 74 68 6f 75 74 0a 2a 2a 20   and without.** 
36590 69 6e 74 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c  intervening call
365a0 73 20 74 6f 20 78 4d 75 74 65 78 45 6e 64 28 29  s to xMutexEnd()
365b0 2e 20 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75  .  Second and su
365c0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
365d0 6f 0a 2a 2a 20 78 4d 75 74 65 78 49 6e 69 74 28  o.** xMutexInit(
365e0 29 20 6d 75 73 74 20 62 65 20 6e 6f 2d 6f 70 73  ) must be no-ops
365f0 2e 0a 2a 2a 0a 2a 2a 20 78 4d 75 74 65 78 49 6e  ..**.** xMutexIn
36600 69 74 28 29 20 6d 75 73 74 20 6e 6f 74 20 75 73  it() must not us
36610 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20  e SQLite memory 
36620 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 5b 73 71 6c  allocation ([sql
36630 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
36640 2a 20 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69  * and its associ
36650 61 74 65 73 29 2e 20 20 53 69 6d 69 6c 61 72 6c  ates).  Similarl
36660 79 2c 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29  y, xMutexAlloc()
36670 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51   must not use SQ
36680 4c 69 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Lite memory.** a
36690 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20  llocation for a 
366a0 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 20 48  static mutex.  H
366b0 6f 77 65 76 65 72 20 78 4d 75 74 65 78 41 6c 6c  owever xMutexAll
366c0 6f 63 28 29 20 6d 61 79 20 75 73 65 20 53 51 4c  oc() may use SQL
366d0 69 74 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ite.** memory al
366e0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 66  location for a f
366f0 61 73 74 20 6f 72 20 72 65 63 75 72 73 69 76 65  ast or recursive
36700 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 53 51   mutex..**.** SQ
36710 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
36720 20 74 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29   the xMutexEnd()
36730 20 6d 65 74 68 6f 64 20 77 68 65 6e 20 5b 73 71   method when [sq
36740 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
36750 5d 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20  ] is.** called, 
36760 62 75 74 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  but only if the 
36770 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d  prior call to xM
36780 75 74 65 78 49 6e 69 74 20 72 65 74 75 72 6e 65  utexInit returne
36790 64 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20  d SQLITE_OK..** 
367a0 49 66 20 78 4d 75 74 65 78 49 6e 69 74 20 66 61  If xMutexInit fa
367b0 69 6c 73 20 69 6e 20 61 6e 79 20 77 61 79 2c 20  ils in any way, 
367c0 69 74 20 69 73 20 65 78 70 65 63 74 65 64 20 74  it is expected t
367d0 6f 20 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72  o clean up after
367e0 20 69 74 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72   itself.** prior
367f0 20 74 6f 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a   to returning..*
36800 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
36810 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
36820 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
36830 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  utex_methods;.st
36840 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
36850 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  ex_methods {.  i
36860 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29  nt (*xMutexInit)
36870 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  (void);.  int (*
36880 78 4d 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29  xMutexEnd)(void)
36890 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  ;.  sqlite3_mute
368a0 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63  x *(*xMutexAlloc
368b0 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28  )(int);.  void (
368c0 2a 78 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c  *xMutexFree)(sql
368d0 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20  ite3_mutex *);. 
368e0 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e   void (*xMutexEn
368f0 74 65 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  ter)(sqlite3_mut
36900 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ex *);.  int (*x
36910 4d 75 74 65 78 54 72 79 29 28 73 71 6c 69 74 65  MutexTry)(sqlite
36920 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f  3_mutex *);.  vo
36930 69 64 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65  id (*xMutexLeave
36940 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
36950 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
36960 65 78 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f  exHeld)(sqlite3_
36970 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20  mutex *);.  int 
36980 28 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29  (*xMutexNotheld)
36990 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
369a0 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  );.};../*.** CAP
369b0 49 33 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72  I3REF: Mutex Ver
369c0 69 66 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  ification Routin
369d0 65 73 20 7b 48 31 37 30 38 30 7d 20 3c 53 32 30  es {H17080} <S20
369e0 31 33 30 3e 20 3c 53 33 30 38 30 30 3e 0a 2a 2a  130> <S30800>.**
369f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
36a00 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64  mutex_held() and
36a10 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e   sqlite3_mutex_n
36a20 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65  otheld() routine
36a30 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65  s.** are intende
36a40 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
36a50 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
36a60 65 6e 74 73 2e 20 7b 48 31 37 30 38 31 7d 20 54  ents. {H17081} T
36a70 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a  he SQLite core.*
36a80 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74 68 65  * never uses the
36a90 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65  se routines exce
36aa0 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73  pt inside an ass
36ab0 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63  ert() and applic
36ac0 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64  ations.** are ad
36ad0 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20  vised to follow 
36ae0 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20  the lead of the 
36af0 63 6f 72 65 2e 20 20 7b 48 31 37 30 38 32 7d 20  core.  {H17082} 
36b00 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a  The core only.**
36b10 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d   provides implem
36b20 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  entations for th
36b30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65  ese routines whe
36b40 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
36b50 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c  .** with the SQL
36b60 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20  ITE_DEBUG flag. 
36b70 20 7b 41 31 37 30 38 37 7d 20 45 78 74 65 72 6e   {A17087} Extern
36b80 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  al mutex impleme
36b90 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ntations.** are 
36ba0 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f  only required to
36bb0 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20 72   provide these r
36bc0 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54  outines if SQLIT
36bd0 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65  E_DEBUG is.** de
36be0 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45  fined and if NDE
36bf0 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e  BUG is not defin
36c00 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38  ed..**.** {H1708
36c10 33 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  3} These routine
36c20 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  s should return 
36c30 74 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65  true if the mute
36c40 78 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d  x in their argum
36c50 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f  ent.** is held o
36c60 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70  r not held, resp
36c70 65 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65  ectively, by the
36c80 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e   calling thread.
36c90 0a 2a 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d 20  .**.** {X17084} 
36ca0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
36cb0 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72  on is not requir
36cc0 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76  ed to provided v
36cd0 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65  ersions of these
36ce0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
36cf0 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e  t actually work.
36d00 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   If the implemen
36d10 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  tation does not 
36d20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a  provide working.
36d30 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  ** versions of t
36d40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69  hese routines, i
36d50 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73  t should at leas
36d60 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 20  t provide stubs 
36d70 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72  that always.** r
36d80 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68  eturn true so th
36d90 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20  at one does not 
36da0 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73 73  get spurious ass
36db0 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e  ertion failures.
36dc0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 35 7d 20  .**.** {H17085} 
36dd0 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
36de0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
36df0 5f 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c  _held() is a NUL
36e00 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
36e10 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68  * the routine sh
36e20 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20  ould return 1.  
36e30 7b 45 4e 44 7d 20 54 68 69 73 20 73 65 65 6d 73  {END} This seems
36e40 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69   counter-intuiti
36e50 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61  ve since.** clea
36e60 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63 61  rly the mutex ca
36e70 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20  nnot be held if 
36e80 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  it does not exis
36e90 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74  t.  But the.** t
36ea0 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75  he reason the mu
36eb0 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69  tex does not exi
36ec0 73 74 20 69 73 20 62 65 63 61 75 73 65 20 74 68  st is because th
36ed0 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a  e build is not.*
36ee0 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e  * using mutexes.
36ef0 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20    And we do not 
36f00 77 61 6e 74 20 74 68 65 20 61 73 73 65 72 74 28  want the assert(
36f10 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
36f20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
36f30 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
36f40 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e   to fail, so a n
36f50 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69  on-zero return i
36f60 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72  s.** the appropr
36f70 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f  iate thing to do
36f80 2e 20 20 7b 48 31 37 30 38 36 7d 20 54 68 65 20  .  {H17086} The 
36f90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
36fa0 74 68 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72  theld().** inter
36fb0 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f  face should also
36fc0 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67   return 1 when g
36fd0 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  iven a NULL poin
36fe0 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ter..*/.int sqli
36ff0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73  te3_mutex_held(s
37000 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
37010 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
37020 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65  x_notheld(sqlite
37030 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a  3_mutex*);../*.*
37040 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
37050 78 20 54 79 70 65 73 20 7b 48 31 37 30 30 31 7d  x Types {H17001}
37060 20 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H17000>.**.** 
37070 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  The [sqlite3_mut
37080 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65  ex_alloc()] inte
37090 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69  rface takes a si
370a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ngle argument.**
370b0 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66   which is one of
370c0 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   these integer c
370d0 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
370e0 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69  The set of stati
370f0 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68  c mutexes may ch
37100 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51  ange from one SQ
37110 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20  Lite release to 
37120 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
37130 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
37140 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69  override the bui
37150 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69  lt-in mutex logi
37160 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65  c must be.** pre
37170 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f  pared to accommo
37180 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  date additional 
37190 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a  static mutexes..
371a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
371b0 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20  E_MUTEX_FAST    
371c0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
371d0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
371e0 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
371f0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
37200 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
37210 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69  ASTER    2.#defi
37220 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37230 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20  STATIC_MEM      
37240 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   3  /* sqlite3_m
37250 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69  alloc() */.#defi
37260 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37270 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20  STATIC_MEM2     
37280 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20   4  /* NOT USED 
37290 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
372a0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f  E_MUTEX_STATIC_O
372b0 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73  PEN      4  /* s
372c0 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28  qlite3BtreeOpen(
372d0 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
372e0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
372f0 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a  _PRNG      5  /*
37300 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28   sqlite3_random(
37310 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
37320 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37330 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a  _LRU       6  /*
37340 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a   lru page list *
37350 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
37360 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
37370 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72  U2      7  /* lr
37380 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a  u page list */..
37390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
373a0 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74  Retrieve the mut
373b0 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  ex for a databas
373c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31  e connection {H1
373d0 37 30 30 32 7d 20 3c 48 31 37 30 30 30 3e 0a 2a  7002} <H17000>.*
373e0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
373f0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
37400 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74  inter the [sqlit
37410 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
37420 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c   that .** serial
37430 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74  izes access to t
37440 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37450 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69  nection] given i
37460 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  n the argument.*
37470 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65  * when the [thre
37480 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53  ading mode] is S
37490 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66  erialized..** If
374a0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
374b0 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d  mode] is Single-
374c0 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d  thread or Multi-
374d0 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 73  thread then this
374e0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
374f0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
37500 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  er..*/.sqlite3_m
37510 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62  utex *sqlite3_db
37520 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29  _mutex(sqlite3*)
37530 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37540 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e  F: Low-Level Con
37550 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65  trol Of Database
37560 20 46 69 6c 65 73 20 7b 48 31 31 33 30 30 7d 20   Files {H11300} 
37570 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b  <S30800>.**.** {
37580 48 31 31 33 30 31 7d 20 54 68 65 20 5b 73 71 6c  H11301} The [sql
37590 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
375a0 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d  l()] interface m
375b0 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61  akes a direct ca
375c0 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69  ll to the.** xFi
375d0 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
375e0 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
375f0 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
37600 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a  ject associated.
37610 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ** with a partic
37620 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64  ular database id
37630 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
37640 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
37650 20 7b 48 31 31 33 30 32 7d 20 54 68 65 0a 2a 2a   {H11302} The.**
37660 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
37670 61 62 61 73 65 20 69 73 20 74 68 65 20 6e 61 6d  abase is the nam
37680 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68  e assigned to th
37690 65 20 64 61 74 61 62 61 73 65 20 62 79 20 74 68  e database by th
376a0 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61  e.** <a href="la
376b0 6e 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e  ng_attach.html">
376c0 41 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63  ATTACH</a> SQL c
376d0 6f 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 65 6e  ommand that open
376e0 65 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  ed the.** databa
376f0 73 65 2e 20 7b 48 31 31 33 30 33 7d 20 54 6f 20  se. {H11303} To 
37700 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e  control the main
37710 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
37720 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61  use the name "ma
37730 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c  in".** or a NULL
37740 20 70 6f 69 6e 74 65 72 2e 20 7b 48 31 31 33 30   pointer. {H1130
37750 34 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  4} The third and
37760 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
37770 72 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  rs to this routi
37780 6e 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64  ne.** are passed
37790 20 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67   directly throug
377a0 68 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20  h to the second 
377b0 61 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d 65  and third parame
377c0 74 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78  ters of.** the x
377d0 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
377e0 6f 64 2e 20 20 7b 48 31 31 33 30 35 7d 20 54 68  od.  {H11305} Th
377f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
37800 66 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  f the xFileContr
37810 6f 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63  ol.** method bec
37820 6f 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e 20  omes the return 
37830 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f  value of this ro
37840 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  utine..**.** {H1
37850 31 33 30 36 7d 20 49 66 20 74 68 65 20 73 65 63  1306} If the sec
37860 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a  ond parameter (z
37870 44 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74  DbName) does not
37880 20 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20   match the name 
37890 6f 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64  of any.** open d
378a0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68  atabase file, th
378b0 65 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  en SQLITE_ERROR 
378c0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 48 31  is returned. {H1
378d0 31 33 30 37 7d 20 54 68 69 73 20 65 72 72 6f 72  1307} This error
378e0 0a 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20  .** code is not 
378f0 72 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77  remembered and w
37900 69 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c  ill not be recal
37910 6c 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  led by [sqlite3_
37920 65 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72  errcode()].** or
37930 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
37940 28 29 5d 2e 20 7b 41 31 31 33 30 38 7d 20 54 68  ()]. {A11308} Th
37950 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69  e underlying xFi
37960 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
37970 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72   might.** also r
37980 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52  eturn SQLITE_ERR
37990 4f 52 2e 20 20 7b 41 31 31 33 30 39 7d 20 54 68  OR.  {A11309} Th
379a0 65 72 65 20 69 73 20 6e 6f 20 77 61 79 20 74 6f  ere is no way to
379b0 20 64 69 73 74 69 6e 67 75 69 73 68 20 62 65 74   distinguish bet
379c0 77 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72  ween.** an incor
379d0 72 65 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64  rect zDbName and
379e0 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   an SQLITE_ERROR
379f0 20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74 68 65   return from the
37a00 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78   underlying.** x
37a10 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
37a20 6f 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  od. {END}.**.** 
37a30 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
37a40 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
37a50 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  E].*/.int sqlite
37a60 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73  3_file_control(s
37a70 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
37a80 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e  har *zDbName, in
37a90 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t op, void*);../
37aa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
37ab0 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65  esting Interface
37ac0 20 7b 48 31 31 34 30 30 7d 20 3c 53 33 30 38 30   {H11400} <S3080
37ad0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
37ae0 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f  ite3_test_contro
37af0 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  l() interface is
37b00 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75   used to read ou
37b10 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74  t internal.** st
37b20 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e  ate of SQLite an
37b30 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c  d to inject faul
37b40 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66  ts into SQLite f
37b50 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75  or testing.** pu
37b60 72 70 6f 73 65 73 2e 20 20 54 68 65 20 66 69 72  rposes.  The fir
37b70 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
37b80 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64  an operation cod
37b90 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  e that determine
37ba0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c  s.** the number,
37bb0 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70   meaning, and op
37bc0 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73  eration of all s
37bd0 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
37be0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ters..**.** This
37bf0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
37c00 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70  t for use by app
37c10 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65  lications.  It e
37c20 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20  xists solely.** 
37c30 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68  for verifying th
37c40 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74  e correct operat
37c50 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
37c60 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65  e library.  Depe
37c70 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20  nding.** on how 
37c80 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
37c90 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20  ry is compiled, 
37ca0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d  this interface m
37cb0 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a  ight not exist..
37cc0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
37cd0 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69  s of the operati
37ce0 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20  on codes, their 
37cf0 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61  meanings, the pa
37d00 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79  rameters.** they
37d10 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20   take, and what 
37d20 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20  they do are all 
37d30 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
37d40 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
37d50 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74  ..** Unlike most
37d60 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41   of the SQLite A
37d70 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  PI, this functio
37d80 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  n is not guarant
37d90 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74  eed to.** operat
37da0 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66  e consistently f
37db0 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
37dc0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
37dd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74  int sqlite3_test
37de0 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c  _control(int op,
37df0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
37e00 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20  PI3REF: Testing 
37e10 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74  Interface Operat
37e20 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 31 34 31  ion Codes {H1141
37e30 30 7d 20 3c 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a  0} <H11400>.**.*
37e40 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
37e50 73 20 61 72 65 20 74 68 65 20 76 61 6c 69 64 20  s are the valid 
37e60 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70  operation code p
37e70 61 72 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a  arameters used.*
37e80 2a 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  * as the first a
37e90 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
37ea0 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c  te3_test_control
37eb0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
37ec0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
37ed0 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61  their meanings a
37ee0 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
37ef0 61 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20  ange.** without 
37f00 6e 6f 74 69 63 65 2e 20 20 54 68 65 73 65 20 76  notice.  These v
37f10 61 6c 75 65 73 20 61 72 65 20 66 6f 72 20 74 65  alues are for te
37f20 73 74 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f  sting purposes o
37f30 6e 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  nly..** Applicat
37f40 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
37f50 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  use any of these
37f60 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74   parameters or t
37f70 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
37f80 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  est_control()] i
37f90 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
37fa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
37fb0 43 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20  CTRL_PRNG_SAVE  
37fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
37fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
37fe0 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53  ESTCTRL_PRNG_RES
37ff0 54 4f 52 45 20 20 20 20 20 20 20 20 20 20 20 20  TORE            
38000 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
38010 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f  E_TESTCTRL_PRNG_
38020 52 45 53 45 54 20 20 20 20 20 20 20 20 20 20 20  RESET           
38030 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
38040 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49  LITE_TESTCTRL_BI
38050 54 56 45 43 5f 54 45 53 54 20 20 20 20 20 20 20  TVEC_TEST       
38060 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
38070 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
38080 5f 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20  _FAULT_INSTALL  
38090 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
380a0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
380b0 54 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f  TRL_BENIGN_MALLO
380c0 43 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23  C_HOOKS     10.#
380d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
380e0 53 54 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42  STCTRL_PENDING_B
380f0 59 54 45 20 20 20 20 20 20 20 20 20 20 20 20 31  YTE            1
38100 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
38110 5f 54 45 53 54 43 54 52 4c 5f 41 53 53 45 52 54  _TESTCTRL_ASSERT
38120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38130 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
38140 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57  ITE_TESTCTRL_ALW
38150 41 59 53 20 20 20 20 20 20 20 20 20 20 20 20 20  AYS             
38160 20 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20       13.#define 
38170 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
38180 52 45 53 45 52 56 45 20 20 20 20 20 20 20 20 20  RESERVE         
38190 20 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a          14../*.*
381a0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69  * CAPI3REF: SQLi
381b0 74 65 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75  te Runtime Statu
381c0 73 20 7b 48 31 37 32 30 30 7d 20 3c 53 36 30 32  s {H17200} <S602
381d0 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
381e0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  TAL.**.** This i
381f0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
38200 20 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e   to retrieve run
38210 74 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f  time status info
38220 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
38230 20 74 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65   the preformance
38240 20 6f 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20   of SQLite, and 
38250 6f 70 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65  optionally to re
38260 73 65 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68  set various.** h
38270 69 67 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20  ighwater marks. 
38280 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
38290 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
382a0 72 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68  r code for.** th
382b0 65 20 73 70 65 63 69 66 69 63 20 70 61 72 61 6d  e specific param
382c0 65 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e  eter to measure.
382d0 20 20 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74    Recognized int
382e0 65 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72  eger codes.** ar
382f0 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53  e of the form [S
38300 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d  QLITE_STATUS_MEM
38310 4f 52 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54  ORY_USED | SQLIT
38320 45 5f 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a  E_STATUS_...]..*
38330 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61  * The current va
38340 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d  lue of the param
38350 65 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  eter is returned
38360 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e   into *pCurrent.
38370 0a 2a 2a 20 54 68 65 20 68 69 67 68 65 73 74 20  .** The highest 
38380 72 65 63 6f 72 64 65 64 20 76 61 6c 75 65 20 69  recorded value i
38390 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  s returned in *p
383a0 48 69 67 68 77 61 74 65 72 2e 20 20 49 66 20 74  Highwater.  If t
383b0 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67 20  he.** resetFlag 
383c0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
383d0 65 20 68 69 67 68 65 73 74 20 72 65 63 6f 72 64  e highest record
383e0 20 76 61 6c 75 65 20 69 73 20 72 65 73 65 74 20   value is reset 
383f0 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77  after.** *pHighw
38400 61 74 65 72 20 69 73 20 77 72 69 74 74 65 6e 2e  ater is written.
38410 20 53 6f 6d 65 20 70 61 72 61 6d 65 74 65 72 73   Some parameters
38420 20 64 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20 74   do not record t
38430 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 76 61  he highest.** va
38440 6c 75 65 2e 20 20 46 6f 72 20 74 68 6f 73 65 20  lue.  For those 
38450 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f  parameters.** no
38460 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  thing is written
38470 20 69 6e 74 6f 20 2a 70 48 69 67 68 77 61 74 65   into *pHighwate
38480 72 20 61 6e 64 20 74 68 65 20 72 65 73 65 74 46  r and the resetF
38490 6c 61 67 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  lag is ignored..
384a0 2a 2a 20 4f 74 68 65 72 20 70 61 72 61 6d 65 74  ** Other paramet
384b0 65 72 73 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20  ers record only 
384c0 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61  the highwater ma
384d0 72 6b 20 61 6e 64 20 6e 6f 74 20 74 68 65 20 63  rk and not the c
384e0 75 72 72 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e  urrent.** value.
384f0 20 20 46 6f 72 20 74 68 65 73 65 20 6c 61 74 74    For these latt
38500 65 72 20 70 61 72 61 6d 65 74 65 72 73 20 6e 6f  er parameters no
38510 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  thing is written
38520 20 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e   into *pCurrent.
38530 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
38540 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
38550 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73  TE_OK on success
38560 20 61 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a   and a non-zero.
38570 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
38580 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  on failure..**.*
38590 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  * This routine i
385a0 73 20 74 68 72 65 61 64 73 61 66 65 20 62 75 74  s threadsafe but
385b0 20 69 73 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20   is not atomic. 
385c0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
385d0 6e 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 77  n be.** called w
385e0 68 69 6c 65 20 6f 74 68 65 72 20 74 68 72 65 61  hile other threa
385f0 64 73 20 61 72 65 20 72 75 6e 6e 69 6e 67 20 74  ds are running t
38600 68 65 20 73 61 6d 65 20 6f 72 20 64 69 66 66 65  he same or diffe
38610 72 65 6e 74 20 53 51 4c 69 74 65 0a 2a 2a 20 69  rent SQLite.** i
38620 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
38630 76 65 72 20 74 68 65 20 76 61 6c 75 65 73 20 72  ver the values r
38640 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 43 75 72  eturned in *pCur
38650 72 65 6e 74 20 61 6e 64 0a 2a 2a 20 2a 70 48 69  rent and.** *pHi
38660 67 68 77 61 74 65 72 20 72 65 66 6c 65 63 74 20  ghwater reflect 
38670 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 53 51  the status of SQ
38680 4c 69 74 65 20 61 74 20 64 69 66 66 65 72 65 6e  Lite at differen
38690 74 20 70 6f 69 6e 74 73 20 69 6e 20 74 69 6d 65  t points in time
386a0 0a 2a 2a 20 61 6e 64 20 69 74 20 69 73 20 70 6f  .** and it is po
386b0 73 73 69 62 6c 65 20 74 68 61 74 20 61 6e 6f 74  ssible that anot
386c0 68 65 72 20 74 68 72 65 61 64 20 6d 69 67 68 74  her thread might
386d0 20 63 68 61 6e 67 65 20 74 68 65 20 70 61 72 61   change the para
386e0 6d 65 74 65 72 0a 2a 2a 20 69 6e 20 62 65 74 77  meter.** in betw
386f0 65 65 6e 20 74 68 65 20 74 69 6d 65 73 20 77 68  een the times wh
38700 65 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e 64  en *pCurrent and
38710 20 2a 70 48 69 67 68 77 61 74 65 72 20 61 72 65   *pHighwater are
38720 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20   written..**.** 
38730 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
38740 65 33 5f 64 62 5f 73 74 61 74 75 73 28 29 5d 0a  e3_db_status()].
38750 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
38760 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
38770 65 33 5f 73 74 61 74 75 73 28 69 6e 74 20 6f 70  e3_status(int op
38780 2c 20 69 6e 74 20 2a 70 43 75 72 72 65 6e 74 2c  , int *pCurrent,
38790 20 69 6e 74 20 2a 70 48 69 67 68 77 61 74 65 72   int *pHighwater
387a0 2c 20 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  , int resetFlag)
387b0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
387c0 45 46 3a 20 53 74 61 74 75 73 20 50 61 72 61 6d  EF: Status Param
387d0 65 74 65 72 73 20 7b 48 31 37 32 35 30 7d 20 3c  eters {H17250} <
387e0 48 31 37 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  H17200>.** EXPER
387f0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
38800 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
38810 74 61 6e 74 73 20 64 65 73 69 67 6e 61 74 65 20  tants designate 
38820 76 61 72 69 6f 75 73 20 72 75 6e 2d 74 69 6d 65  various run-time
38830 20 73 74 61 74 75 73 20 70 61 72 61 6d 65 74 65   status par